From c1d8b81cb93cc430d72a6ccb6dbe7df37129bdd9 Mon Sep 17 00:00:00 2001 From: Abdulrahim Al Methiab Date: Sun, 21 Jan 2024 21:50:39 +0100 Subject: [PATCH 01/19] add version 1.1 --- docs/build/identity.rs/1.1/docs/contact.mdx | 17 + .../build/identity.rs/1.1/docs/contribute.mdx | 49 + .../docs/explanations/about-alias-outputs.mdx | 65 + .../decentralized-identifiers.mdx | 136 + .../explanations/verifiable-credentials.mdx | 74 + .../explanations/verifiable-presentations.mdx | 40 + docs/build/identity.rs/1.1/docs/faq.mdx | 53 + .../1.1/docs/getting-started/rust.mdx | 68 + .../1.1/docs/getting-started/wasm.mdx | 341 + docs/build/identity.rs/1.1/docs/glossary.mdx | 140 + .../decentralized-identifiers/create.mdx | 181 + .../decentralized-identifiers/delete.mdx | 106 + .../decentralized-identifiers/resolve.mdx | 196 + .../decentralized-identifiers/update.mdx | 534 ++ .../domain-linkage/create-and-verify.mdx | 179 + .../1.1/docs/how-tos/key-storage.mdx | 152 + .../how-tos/verifiable-credentials/create.mdx | 160 + .../verifiable-credentials/revocation.mdx | 129 + .../create-and-validate.mdx | 164 + .../1.1/docs/references/api/wasm.mdx | 6251 +++++++++++++++++ .../specifications/iota-did-method-spec.mdx | 263 + .../references/specifications/overview.mdx | 15 + .../specifications/revocation-bitmap-2022.mdx | 201 + docs/build/identity.rs/1.1/docs/welcome.mdx | 91 + docs/build/identity.rs/1.1/docs/workflow.mdx | 179 + docs/build/identity.rs/1.1/sidebars.js | 113 + versionedConfig.js | 4 + 27 files changed, 9901 insertions(+) create mode 100644 docs/build/identity.rs/1.1/docs/contact.mdx create mode 100644 docs/build/identity.rs/1.1/docs/contribute.mdx create mode 100644 docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx create mode 100644 docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx create mode 100644 docs/build/identity.rs/1.1/docs/explanations/verifiable-credentials.mdx create mode 100644 docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx create mode 100644 docs/build/identity.rs/1.1/docs/faq.mdx create mode 100644 docs/build/identity.rs/1.1/docs/getting-started/rust.mdx create mode 100644 docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx create mode 100644 docs/build/identity.rs/1.1/docs/glossary.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx create mode 100644 docs/build/identity.rs/1.1/docs/references/api/wasm.mdx create mode 100644 docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx create mode 100644 docs/build/identity.rs/1.1/docs/references/specifications/overview.mdx create mode 100644 docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx create mode 100644 docs/build/identity.rs/1.1/docs/welcome.mdx create mode 100644 docs/build/identity.rs/1.1/docs/workflow.mdx create mode 100644 docs/build/identity.rs/1.1/sidebars.js diff --git a/docs/build/identity.rs/1.1/docs/contact.mdx b/docs/build/identity.rs/1.1/docs/contact.mdx new file mode 100644 index 00000000000..b9603c18bba --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/contact.mdx @@ -0,0 +1,17 @@ +--- +title: Contact +sidebar_label: Contact +description: Get in touch with the project maintainers. +image: /img/Identity_icon.png +keywords: + - Contact + - GitHub + - Maintainers +--- + +If you found a security related issue, please follow the [responsible disclosure policy](https://github.com/iotaledger/identity.rs/security/policy). + +For everything else, you can get in contact with the project by: + +- Filing an issue on [GitHub](https://github.com/iotaledger/identity.rs). +- Joining the `identity` channel on the [IOTA Discord](https://discord.iota.org/). diff --git a/docs/build/identity.rs/1.1/docs/contribute.mdx b/docs/build/identity.rs/1.1/docs/contribute.mdx new file mode 100644 index 00000000000..810107b0070 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/contribute.mdx @@ -0,0 +1,49 @@ +--- +title: Contribute to the project +sidebar_label: Contribute +description: Contribute to IOTA Identity by joining the Identity initiative, via the projects GitHub repository, documentation, or sharing your knowledge. +image: /img/Identity_icon.png +keywords: + - Contribute + - GitHub + - Identity Initiative + - Documentation + - Discord + - reference +--- + +**Thanks for thinking about contributing to the project! You can contribute using the following ways.** + +## Join the Identity Initiative + +The [Identity Initiative](https://github.com/iota-community/X-Team_IOTA_Identity) is a collaborative effort to help improve the developer experience that includes: + +- Quality assurance and review. +- Documentation. +- Code samples. + +If you would like to get involved, join the [#x-team-identity](https://discord.com/channels/397872799483428865/773274309861834782) channel on [Discord](https://discord.iota.org). + +## Contribute to the Project's GitHub Repository + +All of the code is open source and hosted on [GitHub](https://github.com/iotaledger/identity.rs) where you can: + +- [Report a bug](https://github.com/iotaledger/identity.rs/issues/new/choose). +- [Suggest a new feature](https://github.com/iotaledger/documentation/blob/develop/.github/CONTRIBUTING.md). +- [Contribute to the documentation](/identity.rs/contribute#contribute-to-the-documentation). + +## Contribute to the Documentation + +This documentation is also open source and hosted on GitHub. + +If you want to contribute new documentation or fix an error, see the [contribution guidelines](https://github.com/iotaledger/documentation/blob/develop/.github/CONTRIBUTING.md). + +## Share your Knowledge + +Helping others is an important part of any open source ecosystem. + +By sharing your knowledge with others, you can provide a lot of value to the community and maybe inspire someone else to learn and contribute. + +Take a look at what discussions are going on in the #identity-discussion channel on [Discord](https://discord.iota.org). + +Thanks :heart: diff --git a/docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx b/docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx new file mode 100644 index 00000000000..4a7a0123700 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/explanations/about-alias-outputs.mdx @@ -0,0 +1,65 @@ +--- +title: Alias Outputs +description: UTXO Alias Ouput +image: /img/Identity_icon.png +keywords: + - public keys + - utxo + - Method Specification + - Decentralized Identifiers + - overview + - DLT +--- + +# Alias Outputs + +:::info TL;DR + +The IOTA DID method users Alias Outputs for storing DID Documents. +Alias Outputs are created via transactions, +and require a [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/) to cover the data storage. +The deposit is refundable upon destruction of the output. + +Each Alias Output has an `Alias ID` that becomes the basis for the DID, +and which can be transferred through transactions to update DID Documents. + +::: + + +The IOTA DID method uses the IOTA ledger, which is baed on the unspent transaction output (_UTXO_) model, +as well as the features of the [Stardust](/introduction/stardust/explanations/what_is_stardust) upgrade, +which are fundamental to the IOTA DID method. + +The Alias _Output_ is used to store a DID Document on the ledger. +It is a specific implementation of the UTXO _state machine_ that can hold arbitrary data in its `State Metadata`. +The Alias Output has two kinds of controllers, a state controller and a governor. + +A state controller can execute a state transition which allows updating the data in the `State Metadata`. + +The governor, on the contrary, can't update the `State Metadata` but can change both controllers and destroy the Alias Output. + +A controller can be either Ed25519 Address, [Alias Address or an _NFT_ Address](/learn/protocols/stardust/core-concepts/multi-asset-ledger/) +and at most one of each can be set for an Alias Output. + +In order to create a new Alias Output, a transaction must be made that includes another Output, for example, +a Basic Output, as input and the new Alias Output, along with other outputs if needed, as outputs. + +### Storage Deposit + +The arbitrary data stored in the `State Metadata` of the Alias output must be covered by a +[storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/). +This helps to control the ledger size from growing uncontrollably while guaranteeing the data +is indefinitely stored on the ledger which is important for resolving DID Documents. +This deposit is fully refundable and can be reclaimed when the output is destroyed. + +Both the state controller and the governor can control the tokens stored in the Alias Output. +_Nodes_ expose an API to calculate the required deposit depending on the size of the data stored. + +### Alias ID + +Each Alias Output has an `Alias ID`. This ID is assigned after a transaction creates a new Alias Output. +The actual DID is derived from this `Alias ID`, hence it will be unknown before publishing the transaction. +Consequently, the DID inside the `State Metadata` will be replaced by the placeholder `did:0:0` to indicate self. + +If a transaction has an Alias Output as input, its `Alias ID` can be kept by one of its outputs. +This feature is necessary for updating the DID Documents since the DID itself is derived from the `Alias ID`. diff --git a/docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx b/docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx new file mode 100644 index 00000000000..9702b23e8a6 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/explanations/decentralized-identifiers.mdx @@ -0,0 +1,136 @@ +--- +description: The Decentralized Identifiers (DID) standard from W3C is the fundamental standard that supports the concept of a decentralized digital identity. Explore the basic aspects of the DID standard. +image: /img/Identity_icon.png +keywords: + - public keys + - Method Specification + - Decentralized Identifiers + - overview + - DLT +--- + +# Decentralized Identifiers (DID) + +:::info TL;DR + +DIDs are unique identifiers that can be resolved to DID Documents containing public keys and URIs for identity verification and public information. + +Adhering to the W3C's DID specifications, IOTA's implementation ensures interoperability and security within its ledger. + +DIDs support self-sovereign identity, allowing identity owners to control their creation and destruction, +while facilitating encrypted communication. + +::: + + +A DID is a unique identifier that can be resolved to a DID Document. This document contains data such as public keys, enabling the holder to prove ownership over their personal data, but also URIs that link to public information about the identity. DIDs are the fundamental building blocks of decentralized digital identity. +This implementation complies to the [DID specifications v1.0](https://www.w3.org/TR/did-core//) from the World Wide Web Consortium (W3C). + +In the IOTA Identity framework, we have implemented the DID standard according to the `iota` [DID Method Specification](/identity.rs/references/specifications/iota-did-method-spec/). Other implementations of DID on IOTA must follow the `iota` DID Method Specification if they also want to use the `iota` method name. Libraries implementing the `iota` DID Method Specification are provided for [Rust](../getting-started/rust.mdx) and [WASM](../getting-started/wasm.mdx). + +An example of a DID conforming to the `iota` method specification: +`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe` + +## Decentralized Identifiers + +A Decentralized Identifier, or DID, is a unique identifier that is tied to a subject. This subject can be anything, like a person, an organization, an IoT device, or even an object. The identifier can be used by the subject to identify themselves through a digital format, providing a basis for online identification. The identifier looks like a set of random characters that includes some prefixes to determine which standard and implementation is used: + +`did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe` + +The World Wide Web Consortium (W3C) is a well-known standardization body that has standardized how DIDs should look and work. +This provides a basis for different technologies that implement the [DID standard](https://www.w3.org/TR/did-spec-registries/#did-methods) to achieve interoperability. +Keep in mind that, unfortunately, most of these methods are outdated and not maintained. + +## DID Documents + +The purpose of a DID is to help navigate to a DID Document, +which is a document containing more information regarding the identity subject. +This document contains data such as public keys, enabling the subject to prove ownership over their personal data, +but can contain additional information on how to interact with the subject. + +The identifier contains all information to resolve a DID, providing the latest DID Document. +The first three characters `did` indicate that the DID standard from W3C must be used to resolve the identifier. +It is followed by a unique method name, in our case `iota`, to indicate that the IOTA method is used. + +The IOTA method is a specific implementation following the [IOTA DID Method Specification](/identity.rs/references/specifications/iota-did-method-spec/). +This provides unique rules for the protocol to follow in order to manage a DID Document. +In our case, it describes how DID Documents are uploaded and queried to and from the IOTA ledger. + +Lastly, a DID also contains a set of random characters that are unique per identity and resolve to a single DID Document. + +:::tip Requires basic knowledge of Asymmetric Encryption + +The following sections require some basic knowledge of Asymmetric Encryption. +Please read or view some materials on the subject before continuing. + +::: + +A DID Document mostly contains two important pieces of data: verification methods and services. + +Verification methods contain public key material that can be used to prove ownership over the identity, +by cryptographically signing something with the associated private key. +The public key can be used to verify that the identity subject signed the data and therefore controls the private key. +Ownership over the private keys, therefore, proves ownership over the identity. + +This also means that it is very important to keep the private keys safe and secure. +In addition, the public keys allow users to send encrypted data to the identity that only the identity owner can decrypt. + +:::caution + +Never share your private keys, seeds, passphrases with anyone. Not even IOTA Foundation members. +This may lead to loss of funds or control over your own digital identity. + +::: + +Services are URIs that point to more information about the identity. +This could be something as simple as a website for an organizational identity. +These services are publicly available for all to read, +and should not contain Personal Identifiable Information (PII) in the case of human identities. + +## Why Use DIDs? + +DIDs allow any subject to have a unique identifier that they can prove ownership of, +and at the same time provide a way to send them encrypted messages. +The Identity is Self-Sovereign, meaning the subject is always in control; +whether it is creating, updating or destroying it. + +DIDs become more interesting when you combine them with [verifiable credentials (VC)](verifiable-credentials.mdx). +In essence, verifiable credentials (VCs) are signed statements by trusted third parties about a certain identity. +The signer, or Issuer, is referenced by the DID and so is the subject, often called the holder. +The holder controls a copy of this statement and can share it with other parties, the _Verifiers_, +that can verify the statement and check which party made the statement, without having to ask the Issuer. +Instead, they can verify the signature of the issuer by checking the issuers DID Document. + +This puts Holders back in control over their own data, +while making the data much more trustworthy as it has become verifiable. + +## Why Use Iota Identity Over Other Implementations? + +IOTA Identity is a framework to implement Self-Sovereign Identities on IOTA. +Inherently, IOTA provides some unique features that have a major impact on the usability of the framework. + +### Availability and Accessibility + +DID Documents are stored in the ledger state and are covered [storage deposit](/learn/protocols/stardust/core-concepts/storage-deposit/). +This guarantees that all nodes will have an up-to-date copy of the latest DID Document. +Resolving a DID into its document can usually be done by any IOTA node in the network. +This solves many issues regarding availability, accessibility or synchronization. + +### Layer1 Interactions + +DID Document are stored in an [Alias Outputs](./about-alias-outputs.mdx), +this allows them to directly interact with Layer 1 artifacts like [NFTs and native assets](/learn/protocols/stardust/core-concepts/multi-asset-ledger/). + +For instance, an Alias Output representing a DID can hold native assets or control NFTs. +Transferring funds between DIDs is also possible on Layer 1. + +### Ease-of-use + +IOTA Identity abstracts the details of the DID standard by providing easy-to-use APIs that allow standardized behavior. +It also allows more flexible and complex management of DID Documents. + +### Secure Storage + +IOTA Identity provides a +[Stronghold](/stronghold.rs/welcome/ 'Stronghold is an open-source software library that was originally built to protect IOTA Seeds, but can be used to protect any digital secret.') solution +for managing secrets securely, without requiring developers to reinvent the security wheel. diff --git a/docs/build/identity.rs/1.1/docs/explanations/verifiable-credentials.mdx b/docs/build/identity.rs/1.1/docs/explanations/verifiable-credentials.mdx new file mode 100644 index 00000000000..c06a74426f7 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/explanations/verifiable-credentials.mdx @@ -0,0 +1,74 @@ +--- +description: Verifiable credentials are statements about the holder. They can be verified online or in person, and the holder decides who to share them with. +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - person +--- +# Verifiable Credentials + +:::info TL;DR + +Verifiable credentials (VCs) are digital statements that can be cryptographically proven, like a digital passport, +and are used within systems to assert certain properties or capabilities of an entity. + +In the IOTA Identity framework, this is managed with decentralized identifiers (DIDs) on the Tangle. +Subjects and issuers use their DIDs for the creation and verification of credentials. + +::: + +Credentials are statements about an entity, +such as properties that the entity possesses or capabilities that they have, +like a driver's license, passports, or a person's age. +Verifiable credentials (VCs) are statements (e.g., Alice has a driver's license) +that can be cryptographically verified by a third party, either online or in person. +Additionally, the holder of the VC decides what is shared and who it is shared with. + +There are several types of actors that play different roles in a verifiable credential system. +We'll start with a common example of how things work in the world today using physical credentials and centralized databases, +and outline the roles that various entities play in the Verifiable Credential system. + +## Example - Passport Issuance + +A government (the _issuer_) issues a passport asserting citizenship (the _Verifiable Credential_) to Alice (the _subject_ and _Holder_), +and writes the information to a database (the _Verifiable Data Registry_). +When crossing the border, Alice (the _Holder_) presents her passport to a border agent (the _Verifier_), +who can verify that Alice (the _subject_) is indeed a citizen. + + + +**Subject:** An entity about which claims are made – Alice (the _subject_) is a citizen of this country. + +**Holder:** An entity which possesses verifiable credentials – Alice (the _Holder_) possesses the passport (the _VC_). + +**Issuer:** An entity which asserts claims about a subject – The governing body (the _issuer_), which is trusted, issues Alice a passport. + +**Verifier:** An entity which check's if the VC a holder presents is legitimate – The border agent (the _Verifier_) trusts the government (the _issuer_) which issued Alice her passport, and validates that Alice (the _subject_) is a citizen. + +:::note + +See the [Verifiable Credentials Data Model 1.0 Specification](https://w3c.github.io/vc-data-model/) for more information. + +::: + +## Verifiable Credentials in IOTA + +In the IOTA Identity framework, instead of a physical passport being given to Alice with the information being written +into a centralized database owned by the government, Alice receives a digital verifiable credential, +and the information required for verification in the future is written to the Tangle. + +At a high level, the creation and verification of a VC on IOTA works as follows: + + +The first step is to create a verifiable credential which requires the subject (Alice) and issuer (the government) to +have [DIDs](./decentralized-identifiers.mdx) published on the Tangle, and a set of statements being asserted (that Alice has a passport). +The issuer signs the credential with their private key and publishes the public key to the Tangle. + +Once the issuer is confident that the credential satisfies its expectation, +the credential is stored and transmitted to the subject in a secure manner (off-chain). + +Validation is performed by looking up the issuer's public key on the Tangle, +the holder proving ownership of their DID to the verifier (evidence), +and validating that the credential has indeed been signed by the issuing party. + diff --git a/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx b/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx new file mode 100644 index 00000000000..096ec3734ff --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx @@ -0,0 +1,40 @@ +# Verifiable Presentations + +A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./verifiable-credentials.mdx). +It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation). + +For instance: after an issuer [creates and issues](./../how-tos/verifiable-credentials/create.mdx) a [verifiable credential](./verifiable-credentials.mdx) to a holder, such as a university issuing a degree to a graduate, +the holder stores it securely until asked to present it. +A company could then request proof of that university degree: the holder can [create a verifiable presentation](./../how-tos/verifiable-credentials/create.mdx) +containing their credential, which is already signed by their university, and present it to the company to [validate](./../how-tos/verifiable-credentials/create.mdx#validate-a-vc). + +Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as [GDPR](https://gdpr.eu/). + +:::note + +See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#presentations) for more information on verifiable presentations. + +::: + +## Security Considerations + +### Replay Attacks + +A verifiable presentation without a challenge and domain properties 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). +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. + +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. + +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. \ No newline at end of file diff --git a/docs/build/identity.rs/1.1/docs/faq.mdx b/docs/build/identity.rs/1.1/docs/faq.mdx new file mode 100644 index 00000000000..b3da95f0e4b --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/faq.mdx @@ -0,0 +1,53 @@ +--- +title: Frequently Asked Questions +sidebar_label: FAQ +description: Frequently Asked Question regarding IOTA Identity. +image: /img/Identity_icon.png +keywords: + - FAQ + - Frequently Asked Question + - Troubleshooting + - IOTA Identity +--- + +This page contains frequently asked questions regarding the Identity Library and Self Sovereign Identity in general. + +### What programming languages are supported by the IOTA Identity framework? + +We currently provide a Rust library and a JavaScript library for both the browser and Node.js via WebAssembly (Wasm) bindings. See the "Programming Languages" section for more information. + +### Do I need to have IOTA tokens to start building with IOTA Identity? + +At the moment you don't need IOTA tokens to create and manage identities, although we are exploring opportunities to utilize the token in the future. + +### How do I prove control over my DID? + +Control over an identity is ultimately tied to the control over cryptographic key material (something you have). + +### How do I store my private keys? + +Theoretically you can store the keys however you like. We provide a secure default using IOTA Stronghold where possible, which is a secure software implementation for isolating digital secrets with encrypted storage. For even better guarantees you could look into hardware based key storage. + +### Do I need a Permanode to use IOTA Identity? + +You can get started without one but currently you do require access to a Permanode (a node which stores the entire history of the Tangle) to reliably resolve identities in production. The trustworthiness of this node is very important, since a malicious node could respond with outdated identities, so ideally you should run one yourself or ensure the party supplying the node is trustworthy. + +### Can I use IOTA Identity on Android or iOS? + +We currently do not supply dedicated bindings for Kotlin or Swift. There has been some success running the Wasm bindings on mobile, however. + +### Can I use IOTA Identity on embedded devices? + +We currently do not supply dedicated bindings catering to embedded devices with restricted capabilities. You can try to compile the Rust library for your target platform or use a gateway in front of the devices to handle IOTA Identity interactions. + +### What should I do if my private key is compromised? + +If you still have control over your identity, rotate the key material ASAP! If an attacker has locked you out of your identity, there is not much you can do. Notify contacts that your identity has been compromised and start fresh with a new one. It is for this reason that we suggest using different keys for day-to-day signing and authentication operations, and instead store private keys capable of performing updates to your DID Document securely and separately. + +### Are verifiable credentials stored on the Tangle? + +Verifiable credentials, particularly those with personal identifiable information, are supposed to be stored securely off-Tangle on user devices or systems. As a user, you are in charge of storing your credentials securely and sharing them with other parties on a need-to-know basis. + +### Do I need to hide my DID? Will people be able to identify me by my DID? + +A DID Document should not contain any information linking back to you as a person. However, there is the chance of entities correlating information about you from your DID if used across multiple issuers and verifiers. To minimize this risk, it is advisable to use different DIDs for different use-cases. diff --git a/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx b/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx new file mode 100644 index 00000000000..431e991c5f0 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx @@ -0,0 +1,68 @@ +--- +sidebar_label: Rust +description: Getting started with the IOTA Identity Rust Library. +image: /img/Identity_icon.png +keywords: + - Rust + - Identity +--- +# Getting Started with Rust + +## Requirements + +- [Rust](https://www.rust-lang.org/) (>= 1.62) +- [Cargo](https://doc.rust-lang.org/cargo/) (>= 1.62) + +## Include the Library + +To include IOTA Identity in your project add it as a dependency in your `Cargo.toml`: + +### Latest Stable Release + +This version is published to crates.io and is **stable**, following semantic versioning. + +```toml +[dependencies] +identity_iota = { version = "1.0.0" } +``` + +### Development Release + +This version matches the `main` branch of this repository. It has all the **latest features**, but as such it **may also have undocumented breaking changes**. + +```toml +[dependencies] +identity_iota = { git = "https://github.com/iotaledger/identity.rs", branch = "main"} +``` + +## Examples + +To try out the [examples](https://github.com/iotaledger/identity.rs/tree/main/examples), you should: + +1. Clone the repository: + +```bash +git clone https://github.com/iotaledger/identity.rs +``` + +2. Build the repository: + +```bash +cargo build +``` + +3. Run your first example: + +```bash +cargo run --example getting_started +``` + +## API Reference + +The API reference for the Rust library can be found on [docs.rs](https://docs.rs/identity_iota/latest/identity_iota/index.html). + +If you would like to build the documentation locally you can do so with the following command: + +``` +RUSTDOCFLAGS='--cfg docsrs' cargo +nightly doc -p identity_iota --all-features --no-deps --open +``` diff --git a/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx new file mode 100644 index 00000000000..22978fca285 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx @@ -0,0 +1,341 @@ +--- +sidebar_label: Wasm +description: Getting started with the IOTA Identity WASM Library. +image: /img/Identity_icon.png +keywords: + - WASM + - install + - npm + - yarn + - build + - nodejs + - webpack +--- +# Getting Started with WASM + +## Minimum Requirements + +- [Node.js](https://nodejs.org/en) (>= `v16`) + +## Install the Library + +**Latest Release**: This version matches the `main` branch of this repository. + +You can install the library by running the following command: + +```bash npm2yarn +npm install @iota/identity-wasm +``` + +## Build the Library + +Alternatively, you can build the bindings yourself if you have Rust installed. +If not, refer to [rustup.rs](https://rustup.rs) for the installation. + +### Requirements + +- [Node.js](https://nodejs.org/en) (>= `v16`) +- [Rust](https://www.rust-lang.org/) (>= 1.62) +- [Cargo](https://doc.rust-lang.org/cargo/) (>= 1.62) + +### 1. Install `wasm-bindgen-cli` + +If you want to build the library from source, +you will first need to manually install [`wasm-bindgen-cli`](https://github.com/rustwasm/wasm-bindgen). +A manual installation is required because we use the [Weak References](https://rustwasm.github.io/wasm-bindgen/reference/weak-references.html) feature, +which [`wasm-pack` does not expose](https://github.com/rustwasm/wasm-pack/issues/930). + +```bash +cargo install --force wasm-bindgen-cli +``` + +### 2. Install Dependencies + +After installing `wasm-bindgen-cli`, you can install the necessary dependencies using the following command: + +```bash npm2yarn +npm install +``` + +### 3. Build + + + + + +You can build the bindings for `node.js` using the following command: + +```bash npm2yarn +npm run build:nodejs +``` + + + + + +You can build the bindings for the `web` using the following command: + +```bash npm2yarn +npm run build:web +``` + + + + +## NodeJS Usage + +The following code creates a new IOTA DID Document suitable for publishing to a locally running private network. +See the [instructions](https://github.com/iotaledger/hornet/tree/develop/private_tangle) on running your own private network. + + + + +```typescript +const { + KeyPair, + KeyType, + MethodScope, + IotaDocument, + IotaVerificationMethod, + IotaService, + MethodRelationship, + IotaIdentityClient, +} = require('@iota/identity-wasm/node'); +const { Client } = require('@iota/client-wasm/node'); + +// The endpoint of the IOTA node to use. +const API_ENDPOINT = 'http://127.0.0.1:14265'; + +/** Demonstrate how to create a DID Document. */ +async function main() { + // Create a new client with the given network endpoint. + const client = new Client({ + primaryNode: API_ENDPOINT, + localPow: true, + }); + + const didClient = new IotaIdentityClient(client); + + // Get the Bech32 human-readable part (HRP) of the network. + const networkHrp = await didClient.getNetworkHrp(); + + // Create a new DID document with a placeholder DID. + // The DID will be derived from the Alias Id of the Alias Output after publishing. + const document = new IotaDocument(networkHrp); + + // Insert a new Ed25519 verification method in the DID document. + let keypair = new KeyPair(KeyType.Ed25519); + let method = new IotaVerificationMethod( + document.id(), + keypair.type(), + keypair.public(), + '#key-1', + ); + document.insertMethod(method, MethodScope.VerificationMethod()); + + // Attach a new method relationship to the existing method. + document.attachMethodRelationship( + document.id().join('#key-1'), + MethodRelationship.Authentication, + ); + + // Add a new Service. + const service = new IotaService({ + id: document.id().join('#linked-domain'), + type: 'LinkedDomains', + serviceEndpoint: 'https://iota.org/', + }); + document.insertService(service); + + console.log(`Created document `, JSON.stringify(document.toJSON(), null, 2)); +} + +main(); +``` + +### Expected Output + +``` +Created document { + "doc": { + "id": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000", + "verificationMethod": [ + { + "id": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000#key-1", + "controller": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "z4SxypezRxr1YdMAJBePfHGxZ9hNZ53WVixZq3PbUcztW" + } + ], + "authentication": [ + "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000#key-1" + ], + "service": [ + { + "id": "did:iota:0x0000000000000000000000000000000000000000000000000000000000000000#linked-domain", + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + } + ] + }, + "meta": { + "created": "2022-09-09T11:29:32Z", + "updated": "2022-09-09T11:29:32Z" + } +} +``` + +## Web Usage + +### Set Up + +The library loads the WASM file with an HTTP GET request, so you must copy the `.wasm` file the root of the `dist` folder. + +#### Rollup + +- Install `rollup-plugin-copy`: + +```bash npm2yarn +npm install rollup-plugin-copy --save-dev +``` + +- Add the copy plugin usage to the `plugins` array under `rollup.config.js`: + +```js +// Include the copy plugin +import copy from 'rollup-plugin-copy'; + +// Add the copy plugin to the `plugins` array of your rollup config: +copy({ + targets: [ + { + src: 'node_modules/@iota/client-wasm/web/wasm/client_wasm_bg.wasm', + dest: 'public', + rename: 'client_wasm_bg.wasm', + }, + { + src: 'node_modules/@iota/identity-wasm/web/identity_wasm_bg.wasm', + dest: 'public', + rename: 'identity_wasm_bg.wasm', + }, + ], +}); +``` + +#### Webpack + +- Install `copy-webpack-plugin`: + +```bash npm2yarn +npm install copy-webpack-plugin --save-dev +``` + +```js +// Include the copy plugin +const CopyWebPlugin= require('copy-webpack-plugin'); + +// Add the copy plugin to the `plugins` array of your webpack config: + +new CopyWebPlugin({ + patterns: [ + { + from: 'node_modules/@iota/client-wasm/web/wasm/client_wasm_bg.wasm', + to: 'client_wasm_bg.wasm' + }, + { + from: 'node_modules/@iota/identity-wasm/web/identity_wasm_bg.wasm', + to: 'identity_wasm_bg.wasm' + } + ] +}), +``` + +### Web Usage Example + +```typescript +import * as client from '@iota/client-wasm/web'; +import * as identity from '@iota/identity-wasm/web'; + +/** Demonstrate how to create a DID Document. */ +async function createDocument() { + // Create a new client with the given network endpoint. + const iotaClient = new client.Client({ + primaryNode: API_ENDPOINT, + localPow: true, + }); + + const didClient = new identity.IotaIdentityClient(iotaClient); + + // Get the Bech32 human-readable part (HRP) of the network. + const networkHrp = await didClient.getNetworkHrp(); + + // Create a new DID document with a placeholder DID. + // The DID will be derived from the Alias Id of the Alias Output after publishing. + const document = new identity.IotaDocument(networkHrp); + + // Insert a new Ed25519 verification method in the DID document. + let keypair = new identity.KeyPair(identity.KeyType.Ed25519); + let method = new identity.IotaVerificationMethod( + document.id(), + keypair.type(), + keypair.public(), + '#key-1', + ); + document.insertMethod(method, identity.MethodScope.VerificationMethod()); + + // Attach a new method relationship to the existing method. + document.attachMethodRelationship( + document.id().join('#key-1'), + identity.MethodRelationship.Authentication, + ); + + // Add a new Service. + const service = new identity.IotaService({ + id: document.id().join('#linked-domain'), + type: 'LinkedDomains', + serviceEndpoint: 'https://iota.org/', + }); + document.insertService(service); + + console.log(`Created document `, JSON.stringify(document.toJSON(), null, 2)); +} + +client + .init() + .then(() => identity.init()) + .then(() => { + await createDocument(); + }); + +// or + +(async () => { + await client.init(); + await identity.init(); + + await createDocument(); +})(); + +// Default path is "identity_wasm_bg.wasm", but you can override it like this +await identity.init('./static/identity_wasm_bg.wasm'); +``` + +You need to call `identity.init().then()`, +or `await identity.init()` to load the Wasm file from the server if not available, +because of that **it will only be slow for the first time**. + +## Examples in the Wild + +You may find it useful to see how the WASM bindings are being used in existing applications: + +- [Zebra IOTA Edge SDK](https://github.com/ZebraDevs/Zebra-Iota-Edge-SDK) (mobile apps using Capacitor.js + Svelte) + +## [API Reference](/identity.rs/references/api/wasm) + +## [Examples](https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/README.md) diff --git a/docs/build/identity.rs/1.1/docs/glossary.mdx b/docs/build/identity.rs/1.1/docs/glossary.mdx new file mode 100644 index 00000000000..512d4afc6fb --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/glossary.mdx @@ -0,0 +1,140 @@ +--- +description: Glossary for IOTA Identity, defines the terms used in this specification and throughout decentralized identifier infrastructure. +image: /img/Identity_icon.png +keywords: + - W3C + - terminology + - IOTA + - verification method + - verifiable data registry + - reference +--- + +# Glossary + +This section defines the terms used in this specification, [sourced from W3](https://www.w3.org/TR/did-core/#terminology), and throughout decentralized identifier infrastructure. A link to these terms is included whenever they appear in this specification. + +The first part of the glossary describes the terminology by the W3C. The [second describes](#iota-terminology) the terminology for IOTA-related topics. + +## W3C Terminology + +### Authentication + +A process (typically some type of protocol) by which an entity can prove it has a specific attribute or controls a specific secret using one or more verification methods. With DIDs, a common example would be proving control of the private key associated with a public key published in a DID document. + +### Decentralized Identifier (DID) + +A globally unique persistent identifier that does not require a centralized registration authority because it is generated or registered cryptographically. The generic format of a DID is defined in the DID Core specification. A specific DID scheme is defined in a DID method specification. Many, but not all, DID methods make use of distributed ledger technology (DLT) or some other form of decentralized network. + +### Decentralized Identity Management + +An type of identity management that is based on the use of decentralized identifiers. Decentralized identity management extends authority for identifier generation, registration, and assignment beyond traditional roots of trust such as X.500 directory services, the Domain Name System, and most national ID systems. + +### DID Controller + +An entity that has the capability to make changes to a DID document. A DID may have more than one DID controller. The DID controller(s) can be denoted by the optional controller property at the top level of the DID document. Note that one DID controller may be the DID subject. + +### DID Delegate + +An entity to whom a DID controller has granted permission to use a verification method associated with a DID via a DID document. For example, a parent who controls a child's DID document might permit the child to use their personal device for authentication purposes. In this case, the child is the DID delegate. The child's personal device would contain the private cryptographic material enabling the child to authenticate using the DID. However, the child may not be permitted to add other personal devices without the parent's permission. + +### DID Document + +A set of data describing the DID subject, including mechanisms, such as public keys and pseudonymous biometrics, that the DID subject or a DID delegate can use to authenticate itself and prove its association with the DID. A DID document may also contain other attributes or claims describing the DID subject. A DID document may have one or more different representations as defined in § 6. Core Representations or in the W3C DID Specification Registries [DID-SPEC-REGISTRIES]. + +### DID Fragment + +The portion of a DID URL that follows the first hash sign character (#). DID fragment syntax is identical to URI fragment syntax. + +### DID Method + +A definition of how a specific DID scheme must be implemented to work with a specific verifiable data registry. A DID method is defined by a DID method specification, which must specify the precise operations by which DIDs are created, resolved and deactivated, where DID documents are written and updated. See § 7. Methods. + +### DID Path + +The portion of a DID URL that begins with and includes the first forward-slash (/) character and ends with either a question mark (?) character or a fragment hash sign (#) character (or the end of the DID URL). DID path syntax is identical to URI path syntax. See § 3.2.3 Path. + +### DID Query + +The portion of a DID URL that follows and includes the first question mark character (?). DID query syntax is identical to URI query syntax. See § 3.2.4 Query. + +### DID Resolution + +The function that takes, as an input, a DID and a set of input metadata and returns a DID document in a conforming representation plus additional metadata. This function relies on the "Read" operation of the applicable DID method. The inputs and outputs of this function are defined in § 8. Resolution. + +### DID Resolver + +A DID resolver is a software or hardware component that performs the DID resolution function by taking a DID as input and producing a conforming DID document as output. + +### DID Scheme + +The formal syntax of a decentralized identifier. The generic DID scheme begins with the prefix "did:" as defined in the section of the DID Core specification. Each DID method specification must define a specific DID scheme that works with that particular DID method. In a specific DID method scheme, the DID method name must follow the first colon and terminate with the second colon, such as "did:example:". + +### DID Subject + +The entity identified by a DID and described by a DID document. A DID has exactly one DID subject. Anything can be a DID subject: a person, group, organization, physical thing, digital thing, logical thing, and so on. + +### DID URL + +A DID plus any additional syntactic component that conforms to the definition in § 3.2 DID URL Syntax. This includes an optional DID path, optional DID query (and its leading ? character), and optional DID fragment (and its leading # character). + +### DID URL Dereferencing + +The function that takes as its input a DID URL, a DID document, plus a set of dereferencing options, and returns a resource. This resource may be a DID document plus additional metadata, or it may be a secondary resource contained within the DID document, or it may be a resource entirely external to the DID document. If the function begins with a DID URL, it uses the DID resolution function to fetch a DID document indicated by the DID contained within the DID URL. The dereferencing function can then perform additional processing on the DID document to return the dereferenced resource indicated by the DID URL. The inputs and outputs of this function are defined in § 8.2 DID URL Dereferencing. + +## IOTA Terminology + +### Distributed Ledger (DLT) + +A distributed database in which the various nodes use a consensus protocol to maintain a shared ledger in which each transaction is cryptographically signed and chained to the previous transaction. + +### Public Key Description + +A data object contained inside a DID document that contains all the metadata necessary to use a public key or verification key. + +### Resource + +As defined by [RFC3986]: "...the term 'resource' is used in a general sense for whatever might be identified by a URI." Similarly, any resource may serve as a DID subject identified by a DID. + +### Representation + +As defined for HTTP by [RFC7231]: "information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream of representation data." A DID document is a representation of information describing a DID subject. The § 6. Core Representations section of the DID Core specification defines several representation formats for a DID document. + +### Service + +A means of communicating or interacting with the DID subject or associated entities via one or more service endpoints. Examples include discovery services, agent services, social networking services, file storage services, and verifiable credential repository services. + +### Service Endpoint + +A network address (such as an HTTP URL) at which a service operates on behalf of a DID subject. + +### Uniform Resource Identifier (URI) + +The standard identifier format for all resources on the World Wide Web as defined by [RFC3986]. A DID is a type of URI scheme. + +### Verifiable Credential + +A standard data model and representation format for cryptographically-verifiable digital credentials as defined by the W3C [VC-DATA-MODEL]. + +### Verifiable Data Registry + +A system that facilitates the creation, verification, updating, or deactivation of decentralized identifiers and DID documents. A verifiable data registry may also be used for other cryptographically-verifiable data structures such as verifiable credentials. For more information, see [VC-DATA-MODEL]. + +### Verifiable Timestamp + +A verifiable timestamp enables a third-party to verify that a data object existed at a specific moment in time and that it has not been modified or corrupted since that moment in time. If the data integrity were to be reasonably modified or corrupted since that moment in time, the timestamp is not verifiable. + +### Verification Method + +A set of parameters that can be used together with a process or protocol to independently verify a proof. For example, a public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated private key. + +"Verification" and "proof" in this definition are intended to apply broadly. For example, a public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof." + +### Verification Relationship + +An expression of the relationship between the DID subject and a verification method. An example of a verification relationship is § 5.4.1 authentication. + +### Universally Unique Identifier (UUID) + +A type of globally unique identifier defined by [RFC4122]. UUIDs are similar to DIDs in that they do not require a centralized registration authority. UUIDs differ from DIDs in that they are not resolvable or cryptographically-verifiable. +In addition to the terminology above, this specification also uses terminology from the [INFRA] specification to formally define the abstract data model. When [INFRA] terminology is used, such as string, ordered set, and map, it is linked directly to that specification. diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx new file mode 100644 index 00000000000..5c3f0bccc25 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx @@ -0,0 +1,181 @@ +--- +title: Creating a Decentralized Identity +sidebar_label: Create and Publish +description: Create DID Documents and publish them to the Tangle +image: /img/Identity_icon.png +keywords: + - Documents + - DID + - Tangle + - Create + - Publish +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +If you want to benefit from Self-Sovereign Identity, +you need to create a [Decentralized Identity](../../explanations/decentralized-identifiers.mdx). +This identity consists of many parts that have different functions. + +:::note DID method Specification + +Note that the Iota Identity Framework follows [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx). + +::: + +## Identity Generation Process + + +### 1. Get Funds to Cover the Storage Deposit + +The first thing you will need to generate an identity is an address with enough funds to cover +the [Storage Deposit](../../explanations/about-alias-outputs.mdx#storage-deposit). +In test networks, you can use a [faucet](https://faucet.testnet.shimmer.network/) to request funds. + +:::tip + +If you want to use the main Shimmer or IOTA networks, +you will need an output with actual Shimmer or IOTA funds to create a new Alias Output that represents a DID. + +::: + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L52 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51 +``` + + + +
+ +### 2. Create the Content for the DID Document + +As a bare minimum, a [DID document](../../explanations/decentralized-identifiers.mdx) needs at least one verification method. + +At this point the DID itself is unknown since the Alias Output is not published yet and didn't get an `Alias ID` assigned. + +:::tip + +You can use a placeholder `did:iota:0x0000000000000000000000000000000000000000000000000000000000000000` to reference +the DID inside the document. + +::: + +
+ + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L59-L71 +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65 +``` + + + +
+ +### 3. Construct a New Alias Output + +Next, you need to construct a new [Alias Output](../../explanations/about-alias-outputs.mdx) that includes the +DID Document in the [State Metadata](../../explanations/about-alias-outputs.mdx). +The created Alias Output contains an encoded version of the DID Document in its `State Metadata`, and has the state +controller and the governor set to the generated Ed25519 address. + +Note that controllers don't need to be Ed25519 addresses, they can be any type of output. +However, they must be unlocked in order perform a state or governance transition when the DID Document is updated or destroyed. + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L75 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70 +``` + + + +
+ +### 4. Publish the generated Alias Output. + +The byte cost for the document is automatically calculated and a new transaction is published that includes +the Basic Output as input and the newly generated Alias Output as output, as well as another Basic Output which contains +the remaining token. + +The DID is only known once the [Alias Output](../../explanations/about-alias-outputs.mdx) is successfully published, +since the DID's [Tag](../../references/specifications/iota-did-method-spec.mdx#iota-tag) contains the +[Alias ID](../../explanations/about-alias-outputs.mdx#alias-id). +Once the transaction is confirmed, the `Alias ID` is assigned, and the DID can be derived from it, +the DID Document is stored on the ledger and can be [resolved](resolve.mdx) using any node. + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs#L78 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74 +``` + + + +
+ +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/0_create_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/0_create_did.ts +``` + + + + +## Running a Private Network + +In order to run the examples, you will need to run a private network needs to run locally. +You can refer to [Hornet repository](https://github.com/iotaledger/hornet/tree/develop/private_tangle) for instructions on how to run a private network. + +If your local private network uses different ports than Hornet, modify the API and faucet endpoints in the examples +to match your local setup. diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx new file mode 100644 index 00000000000..465cafff339 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx @@ -0,0 +1,106 @@ +--- +title: Delete an IOTA Identity +sidebar_label: Delete +description: How to deactivate or destroy an IOTA Identity +image: /img/Identity_icon.png +keywords: + - Delete + - Deactivate + - Destroy +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +There are two approaches to delete an IOTA Identity, with different implications: + +- [Deactivate](#deactivate) +- [Destroy](#destroy) + +## Deactivate + +As detailed in the [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx#deactivate), +the state controller of an IOTA Identity may [deactivate](https://www.w3.org/TR/did-core/#did-document-metadata) it by publishing an update that either: + +- deletes the contents of the DID Document entirely, leaving the state metadata empty, OR +- sets the `deactivated` field in the DID Document metadata to `true`. + +In both cases, the DID Document will be marked as `deactivated` when resolved. + +:::tip Reversible + +The identity can be reactivated at any time, by publishing an update restoring the DID Document's contents, +or unsetting the `deactivated` field in the metadata respectively, depending on how it was initially deactivated. + +Note that if the governor is different from the state controller, it cannot deactivate an identity directly because +it is disallowed from updating the DID Document, but it may [destroy](#destroy) it. + +::: + +### Example + +The following example demonstrates deactivating and reactivating an IOTA DID Document, +and optionally reclaiming the storage deposit. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/3_deactivate_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/3_deactivate_did.ts +``` + + + + +## Destroy + +Alternatively, you can [destroy](../../references/specifications/iota-did-method-spec.mdx#destroy) an IOTA Identity can be permanently. + +:::warning Irreversible + +Destroying an IOTA Identity is permanent and irreversible. + +::: + + +This is achieved by the governor of a DID publishing a transaction consuming the [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) +containing the IOTA DID Document, without a corresponding Alias Output on the output side. + +Any coins and tokens in the Alias Output are reclaimed and can be sent to another address. + +:::warning + +Note that historical versions may still be stored off-ledger, or on a permanode, +so sensitive or Personal Identifiable Information (PII) should NEVER be stored in a DID Document. + +::: + +Even with a previous version available, a destroyed DID can never be restored. + +### Example + +The following example demonstrates a governor destroys an IOTA Identity and sends the storage deposit back to itself. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/4_delete_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/4_delete_did.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx new file mode 100644 index 00000000000..87814227334 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx @@ -0,0 +1,196 @@ +--- +title: Resolve an IOTA Identity +sidebar_label: Resolve +description: Explain how resolving works including arguments +image: /img/Identity_icon.png +keywords: + - Resolve +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +DID resolution is the process of fetching and decoding a [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) corresponding to a given [DID](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). +The [IOTA Identity framework](https://github.com/iotaledger/identity.rs) supports resolving DID Documents that are +stored on the IOTA and Shimmer networks and enables users to plug in handlers for additional methods. + +This is similar to, but not to be confused with, +the [W3C DID Resolution specification](https://w3c-ccg.github.io/did-resolution/), +which defines function signatures for resolution in the context of web or REST APIs, +whereas the IOTA Identity framework provides strongly-typed resolution for a better developer experience. + +This functionality is primarily provided by the `Resolver`, which can: + +- [Resolve Iota DID Documents](#resolving-an-iota-did). +- [Resolve DID Documents from multiple DID methods](#resolving-multiple-did-methods). +- Resolve the DID Documents referenced in a verifiable presentation or credential. + +## Resolving an IOTA DID + +The following examples demonstrate how to resolve an IOTA DID Document from its DID. + +### Resolver + +Once you have configured `Resolver` with a [`Client`](/iota-sdk/welcome), it will resolve +IOTA DID Documents according to the read procedure defined in the [IOTA DID Method Specification](../../references/specifications/iota-did-method-spec.mdx#read). +It fetches the latest [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) from the network specified in the DID (see [DID Format](../../references/specifications/iota-did-method-spec.mdx#did-format)), +then extracts and validates the DID Document from it. + + + + +```rust +use identity_iota::iota::IotaDID; +use identity_iota::iota::IotaDocument; +use identity_iota::resolver::Resolver; +use iota_sdk::client::Client; + +#[tokio::main] +async fn main() -> anyhow::Result<()>{ + // Configure a client for the Shimmer testnet "rms". + let node_url = "https://api.testnet.shimmer.network/"; + let client = Client::builder() + .with_primary_node(node_url, None)? + .finish()?; + + // Construct a resolver using the client. + let mut resolver = Resolver::::new(); + resolver.attach_iota_handler(client); + + // Parse the DID and resolve its DID Document. + let did = IotaDID::parse("did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47")?; + let document: IotaDocument = resolver.resolve(&did).await?; + + Ok(()) +} +``` + + + + +```js +const { + Resolver, + IotaDID, + IotaIdentityClient, +} = require('@iota/identity-wasm/node'); +const { Client } = require('@iota/client-wasm/node'); + +// Configure a client for the Shimmer testnet "rms". +const nodeUrl = 'https://api.testnet.shimmer.network/'; +const client = new Client({ + primaryNode: nodeUrl, + localPow: true, +}); +const didClient = new IotaIdentityClient(client); + +// Construct a resolver using the client. +const resolver = new Resolver({ + client: didClient, +}); + +// Resolve the given did +const did = + 'did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47'; +const document = await resolver.resolve(did); +``` + + + + +### Client + +You can also use the [`Client`](/iota-sdk/welcome) directly to resolve individual DIDs from its configured network. + + + + +```rust +use identity_iota::iota::IotaDID; +use identity_iota::iota::IotaDocument; +use identity_iota::iota::IotaIdentityClientExt; +use iota_sdk::client::Client; + +#[tokio::main] +async fn main() -> anyhow::Result<()>{ + // Configure a client for the Shimmer testnet "rms". + let node_url = "https://api.testnet.shimmer.network/"; + let client = Client::builder() + .with_primary_node(node_url, None)? + .finish()?; + + // Parse the DID and resolve its DID Document. + let did = IotaDID::parse("did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47")?; + let document: IotaDocument = client.resolve_did(&did).await?; + Ok(()) +} +``` + + + + +```js +const { IotaDID, IotaIdentityClient } = require('@iota/identity-wasm/node'); +const { Client } = require('@iota/client-wasm/node'); + +// Configure a client for the Shimmer testnet "rms". +const nodeUrl = 'https://api.testnet.shimmer.network/'; +const client = new Client({ + primaryNode: nodeUrl, + localPow: true, +}); +const didClient = new IotaIdentityClient(client); + +// Parse the DID and resolve its DID Document. +const did = IotaDID.parse( + 'did:iota:rms:0x7b48b06232b8a1e7a31c314cab1ceedb84e2e9dd2b1fae79b67eaa4595f15e47', +); +const document = await didClient.resolveDid(did); +``` + + + + +## Advanced Resolver Configuration + +You can configure the `Resolver` to support many use cases by attaching custom resolution handlers. +This enables the `Resolver` to resolve multiple DID methods as well as customizing how +a particular DID method (such as the IOTA method) gets resolved. + +This feature is mainly intended to be used together with the Resolver's convenience methods for +handling [verifiable presentations](../verifiable-presentations/create-and-validate.mdx) +and [credentials](./../../explanations/verifiable-credentials.mdx). + +### Resolving Multiple DID Methods + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/5_custom_resolution.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/4_custom_resolution.ts +``` + + + + +## Resolution for Verifiable Presentations + +When validating [verifiable presentations](./../verifiable-presentations/create-and-validate.mdx), you need to +resolve the DID Documents of the [verifiable credential](./../../explanations/verifiable-credentials.mdx) issuers +and presentation holder to verify their signatures. + +Resolving the necessary DID Documents is +[performed automatically when verifying presentations via the `Resolver`](../verifiable-presentations/create-and-validate.mdx#example) + +When direct access to these DID Documents is desired, the `Resolver` also provides standalone methods to: + +- Resolve a presentation holder's DID Document. +- Resolve the DID Documents of the issuers of the credentials in a verifiable presentation. +- Resolve the issuer's DID Document for a given verifiable credential. diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx new file mode 100644 index 00000000000..c888221877b --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx @@ -0,0 +1,534 @@ +--- +sidebar_label: Update +description: How DID Documents can be manipulated and how updates should be published +image: /img/Identity_icon.png +keywords: + - Documents + - DID + - Tangle + - Update + - Publish +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Update DID Documents + +You can extend DID Documents by adding [verification methods](#verification-methods), [services](#services) and custom properties. +A verification method adds public keys, which can be used to digitally sign things like a DID message or a verifiable credential, +while a service can provide metadata around the identity via URIs. + +## Verification Methods + +As demonstrated by the [example](#example) below, the IOTA Identity framework offers easy-to-use methods for adding +[verification methods](https://www.w3.org/TR/did-core/#verification-methods). + +### Properties + +You can specify the following properties for a verification method: + +- **id**: A [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for the verification method. You can specify it by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). +- **type**: Specifies the type of the verification method. The framework supports `Ed25519` and `X25519` key types. This property is automatically filled by the framework when specifying the verification material. +- **publicKeyMultibase**: A multi-base encoded public key which concludes the [verification material](https://www.w3.org/TR/did-core/#verification-material). This can be automatically generated by the framework or manually provided by users. + +## Verification Relationships + +[Verification relationships](https://www.w3.org/TR/did-core/#verification-relationships) express the relationship between the DID subject and the verification method. +You can use it to specify the purpose of the verification method. + +### Relationships + +The following relationships are supported by the Identity Framework: + +- **[Authentication](https://www.w3.org/TR/did-core/#authentication)**: Used to specify authentication methods for the DID subject. +- **[Assertion](https://www.w3.org/TR/did-core/#assertion)**: Used to verify verifiable credentials. +- **[Key Agreement](https://www.w3.org/TR/did-core/#assertion)**: Used for establishing secure communication channels. +- **[Capability Invocation](https://www.w3.org/TR/did-core/#capability-invocation)**: Can be used to authorize updates to the DID Document. +- **[Capability Delegation](https://www.w3.org/TR/did-core/#capability-delegation)**: A mechanism to delegate cryptographic capability to another party. + +Verification methods can be either [embedded or referenced](https://www.w3.org/TR/did-core/#referring-to-verification-methods). Referencing verification +methods allows them to be used by more than one verification relationship. +When you create a verification method using the identity framework, specifying the `MethodScope` option will result in an embedded verification method. +Leaving that option unset will create the verification method as a map entry of the `verificationMethod` property. +You can also add verification relationships afterward using references. + +:::note + +Updates to the DID Document are done through a state transition of the [Alias Output](../../references/specifications/iota-did-method-spec.mdx#alias-output) by its state controller. +The public key or address of the state controller does not need to be a verification method in the DID Document, +since it is defined in the containing Alias Output. + +::: + +## Services + +[Services](https://www.w3.org/TR/did-core/#services) allow you to add other ways of communicating with the DID subject. +An endpoint included in the DID Document can offer a way of reaching services for different purposes +like authentication, communicating, and discovery. + +### Properties + +You can specify the following properties for a service: + +- **id**: A [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for referencing the service in the DID document. You can specify it by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). +- **type**: A string used to maximize interoperability between services. The framework does not perform any checks on the content of this string. +- **serviceEndpoint**: A URL that points to the service endpoint. + +## Create Identity + +Before you can update anything, you will need to [create an Identity](./create.mdx). + + + + +```rust + // Create a new client to interact with the IOTA ledger. + let client: Client = Client::builder() + .with_primary_node(API_ENDPOINT, None)? + .finish() + .await?; + + // Create a new secret manager backed by a Stronghold. + let mut secret_manager: SecretManager = SecretManager::Stronghold( + StrongholdSecretManager::builder() + .password(Password::from("secure_password".to_owned())) + .build(random_stronghold_path())?, + ); + + // Create a new DID in an Alias Output for us to modify. + let storage: MemStorage = MemStorage::new(JwkMemStore::new(), KeyIdMemstore::new()); + let (_, document, fragment_1): (Address, IotaDocument, String) = + create_did(&client, &mut secret_manager, &storage).await?; + let did: IotaDID = document.id().clone(); + +``` + + + + +```js + const client = new Client({ + primaryNode: API_ENDPOINT, + localPow: true, + }); + const didClient = new IotaIdentityClient(client); + + // Generate a random mnemonic for our wallet. + const secretManager: MnemonicSecretManager = { + mnemonic: Utils.generateMnemonic(), + }; + + // Creates a new wallet and identity (see "0_create_did" example). + const storage: Storage = new Storage(new JwkMemStore(), new KeyIdMemStore()); + let { document, fragment } = await createDid( + client, + secretManager, + storage, + ); +``` + + + + +This creates and publishes an Alias Output containing a DID Document with one verification method. + +```json +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Add a Verification Method + + + + +```rust + // Insert a new Ed25519 verification method in the DID document. + let fragment_2: String = document + .generate_method( + &storage, + JwkMemStore::ED25519_KEY_TYPE, + JwsAlgorithm::EdDSA, + None, + MethodScope::VerificationMethod, + ) + .await?; +``` + + + + +```js + // Insert a new Ed25519 verification method in the DID document. + await document.generateMethod( + storage, + JwkMemStore.ed25519KeyType(), + JwsAlgorithm.EdDSA, + "#key-2", + MethodScope.VerificationMethod(), + ); +``` + + + + +This creates a new verification method that includes a newly generated Ed25519 public key. + +```json +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + }, + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +Notice that these changes to the document are not [published](#publish-your-updates) yet. + +## Add Verification Relationships + +You can attach verification relationships to a verification method by referencing its fragment. + + + + +```rust +// Attach a new method relationship to the inserted method. +document.attach_method_relationship( + &document.id().to_url().join(format!("#{fragment_2}"))?, + MethodRelationship::Authentication, +)?; +``` + + + + +```js +// Attach a new method relationship to the inserted method. +document.attach_method_relationship( + &document.id().to_url().join(format!("#{fragment_2}"))?, + MethodRelationship::Authentication, +)?; +``` + + + + +This will add `Authentication` relationship to the verification method with the fragment `key-1`. +Note that `Authentication` references the already included `key-2` verification method: + +```json {12,19} +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + }, + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ], + "authentication": [ + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:03Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Add a Service + +You can also add custom properties can to a service by setting `properties`: + + + + +```rust + // Add a new Service. + let service: Service = Service::from_json_value(json!({ + "id": document.id().to_url().join("#linked-domain")?, + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + }))?; + assert!(document.insert_service(service).is_ok()); + document.metadata.updated = Some(Timestamp::now_utc()); +``` + + + + +```js + // Add a new Service. + const service: Service = new Service({ + id: did.join("#linked-domain"), + type: "LinkedDomains", + serviceEndpoint: "https://iota.org/", + }); + document.insertService(service); + document.setMetadataUpdated(Timestamp.nowUTC()); +``` + + + + +The updated Document with the newly created service looks as follows. + +```json {21-27} +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "HZ11e0XacuODQw5FcoMHtcdxl8oXHbSnIhQMUgVzWBE", + "crv": "Ed25519", + "x": "475CGLtezvySFMCHhx6hE9S97MIYMLb4B-pbVEHaCtY" + } + }, + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ], + "authentication": [ + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" + ], + "service": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#linked-domain", + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:08Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Remove a Verification Method + +You can also remove verification methods at any time using the following snippet: + + + + +```rust +// Remove a verification method. +let original_method: DIDUrl = document.resolve_method(fragment_1.as_str(), None).unwrap().id().clone(); +document.purge_method(&storage, &original_method).await.unwrap(); +``` + + + + +```js +// Remove a verification method. +let originalMethod = document.resolveMethod(fragment) as VerificationMethod; +await document.purgeMethod(storage, originalMethod?.id()); +``` + + + + +This removes the original verification method with the fragment `key-1`. + +```json +{ + "doc": { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "verificationMethod": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "controller": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE", + "crv": "Ed25519", + "x": "h8ndZ4_Urmzf4xN4emqS8r5q4pAQvAh0k2YHq5JLBBo" + } + } + ], + "authentication": [ + "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#yJz-sPlCmd432JKqK_hkiPml2kj22Jv0aAFy_2jJ8nE" + ], + "service": [ + { + "id": "did:iota:tst:0x19ed80fbd2a644fc2347e27e46e09d42b89df9b1ba09ae41832a9d47d686776a#linked-domain", + "type": "LinkedDomains", + "serviceEndpoint": "https://iota.org/" + } + ] + }, + "meta": { + "created": "2023-11-16T20:40:03Z", + "updated": "2023-11-16T20:40:08Z", + "governorAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd", + "stateControllerAddress": "tst1qrjsnlg6nqd2kdzx4q880nl74jtrcajm7ae57zazl0l7ye09ahh4x6z9gtd" + } +} +``` + +## Publish Your Updates + +Publish the updated DID Document inside the Alias Output taking into account the increase in the storage deposit needed. + + + + +```rust + // Resolve the latest output and update it with the given document. + let alias_output: AliasOutput = client.update_did_output(document.clone()).await?; + + // Because the size of the DID document increased, we have to increase the allocated storage deposit. + // This increases the deposit amount to the new minimum. + let rent_structure: RentStructure = client.get_rent_structure().await?; + let alias_output: AliasOutput = AliasOutputBuilder::from(&alias_output) + .with_minimum_storage_deposit(rent_structure) + .finish()?; + + // Publish the updated Alias Output. + let updated: IotaDocument = client.publish_did_output(&secret_manager, alias_output).await?; +``` + + + + +```js + // Resolve the latest output and update it with the given document. + let aliasOutput: AliasOutput = await didClient.updateDidOutput(document); + + // Because the size of the DID document increased, we have to increase the allocated storage deposit. + // This increases the deposit amount to the new minimum. + const rentStructure: IRent = await didClient.getRentStructure(); + + aliasOutput = await client.buildAliasOutput({ + ...aliasOutput, + amount: Utils.computeStorageDeposit(aliasOutput, rentStructure), + aliasId: aliasOutput.getAliasId(), + unlockConditions: aliasOutput.getUnlockConditions(), + }); + + // Publish the output. + const updated: IotaDocument = await didClient.publishDidOutput(secretManager, aliasOutput); +``` + + + + +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/1_update_did.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/1_update_did.ts +``` + + + \ No newline at end of file diff --git a/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx b/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx new file mode 100644 index 00000000000..c01de0c4c23 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx @@ -0,0 +1,179 @@ +--- +description: How to link a domain and a DID +sidebar_label: Create and Verify +image: /img/Identity_icon.png +keywords: + - well-known + - domain linkage + - DID Configuration Resource + - Domain Linkage Credential +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Domain Linkage + +:::info +To use Domain Linkage in Rust you have to enable the `domain-linkage` feature. +::: + +## Overview + +Domain Linkage can provide proof for a connection between a DID and a domain being controlled by the same entity. +This linkage can transfer trust from a domain to a DID and vice versa. +For instance, if an entity trusts a domain, it can also trust the linked DID and all documents signed by +the verification methods included in the DID Document. + +A use case could be a verifier that trusts `www.example.com`, and receives a verifiable presentation issued by `did:foo:abc`. +If `did:foo:abc` is linked to `www.example.com`, the verifier can trust that the verifiable presentation is issued by +the same entity controlling `www.example.com`. +The DIF has approved a [Well Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) draft to standardize this connection by introducing +the [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) and the [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint). + +![Identity getting started](/img/domain-linkage-diagram.png) + +### DID Configuration Resource + +Suppose that a DID `did:foo:example` with the following DID Document only contains one `verificationMethod`, `key-1`: + +```json {5} +{ + "id": "did:foo:abc", + "verificationMethod": [ + { + "id": "did:foo:abc#key-1", + "controller": "did:foo:abc", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "zDShpHKXkcHKHcF8CnGAA1UqyyuEPRNz1XFEuggbWJQSq" + } + ] + }, +``` + +The domain `https://www.example.com` represents the same entity and needs to be linked to increase trust in the DID. + +To establish this link, you must create a [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource), +and make it available on the [DID Configuration URL](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-uri). +In this case it's `https://example.com/.well-known/did-configuration.json`. + +The [DID Configuration Resource](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource) is a JSON-LD object containing verifiable credentials called `Domain Linkage Credentials`. +Each credential represents a linkage to a single DID. + +:::note + +Note that one `DID Configuration Resource` can include multiple `Domain Linkage Credentials`, +effectively linking the same domain to multiple DIDs. + +::: + +In this example, the domain `https://www.example.com` needs to be linked to the DID `did:foo:abc`. +This means that the `DID Configuration Resource` will have one `Domain Linkage Credential`. +This credential must have the following properties: + +- Its `type` includes `DomainLinkageCredential`. +- It includes the DID Configuration context. +- The `credentialSubject` must be the DID `did:foo:abc` and references the domain `https://www.example.com`. +- The issuer is the DID itself `did:foo:abc`. +- It is signed by a key material included in the DID Document, in this case `did:foo:abc#key-1`. + +```json +{ + "@context": "https://identity.foundation/.well-known/did-configuration/v1", + "linked_dids": [ + { + "@context": [ + "https://www.w3.org/2018/credentials/v1", + "https://identity.foundation/.well-known/did-configuration/v1" + ], + "type": ["VerifiableCredential", "DomainLinkageCredential"], + "credentialSubject": { + "id": "did:foo:abc", + "origin": "https://www.example.com/" + }, + "issuer": "did:foo:abc", + "issuanceDate": "2023-02-09T22:14:15Z", + "expirationDate": "2024-02-09T22:14:15Z", + "proof": { + "type": "JcsEd25519Signature2020", + "verificationMethod": "did:foo:abc#key-1", + "signatureValue": "4SvYqo3YoArfW7r7qKfN7RUJdZnBteb166KE4UkX8MNdbp5UW6YbykneAzvjyRmf5EVQ9bnP9cS5sbEPUn2uaAcB" + } + } + ] +} +``` + +Now this `DID Configuration Resource` must be made available on `https://example.com/.well-known/did-configuration.json`, +which establishes the linkage. + +### Linked Domain Service Endpoint + +By having a domain, one can discover what DIDs are linked to it by fetching the `DID Configuration Resource` and +investigating the `Domain Linkage Credentials`. + +If you want to enable discovery from the other direction, that is, if you have a DID and want to discover which +domains are linked to it, you can add a [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint) to the DID Document. +The DID Document from this example will be extended as follows to enable discovery of `https://www.example.com`: + +```json {11-17} +{ + "id": "did:foo:abc", + "verificationMethod": [ + { + "id": "did:foo:abc#key-1", + "controller": "did:foo:abc", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "zDShpHKXkcHKHcF8CnGAA1UqyyuEPRNz1XFEuggbWJQSq" + } + ], + "service": [ + { + "id": "did:foo:abc#domain-linkage", + "type": "LinkedDomains", + "serviceEndpoint": "https://www.example.com/" + } + ] +} +``` + +:::note +Note that a DID Document can have multiple `Linked Domain Services` and each service can link to multiple domains. +::: + +### Verifying a DID and Domain Linkage + +As mentioned above, you can discover the Domain Linkage from either direction. +But verifying the linkage in both cases involves only verifying the DID Configuration Resource. +The process is as follows: + +1. Fetch `DID Configuration Resource` from `https://www.example.com/.well-known/did-configuration.json`. +2. Resolve the DID Document of `did:foo:abc`. +3. Verify the `DID Configuration Resource` and its `Domain Linkage Credential` that references `did:foo:abc`. + + +:::tip About DID Configuration Resource Verification + +You can learn more +[about DID Configuration Resource Verification on the Identity Foundation website](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification). + +::: + +## Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/6_domain_linkage.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/5_domain_linkage.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx b/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx new file mode 100644 index 00000000000..1e1fdb28673 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx @@ -0,0 +1,152 @@ +--- +title: Key Storage +sidebar_label: Key Storage +description: Explain the use of the storage interfaces and how they can be implemented +image: /img/Identity_icon.png +keywords: + - key storage + - storage interfaces + - json web key + - json web algorithm + - signing +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Introduction + +The `JwkDocumentExt` API allows you to modify a DID document, for example, adding new verification methods. +It enables storing the secrets that verification methods represent in a secure manner. +It does so by using the two storage interfaces, namely the `JwkStorage` and `KeyIdStorage`. +We refer to both of these as the **key storage**. + +The main idea behind the key storage is strongly inspired by the architecture of key management systems (KMS) +or secure enclaves: once private keys are entered into the system, they can never be retrieved again. +Instead, all operations using the key will have to go through that system. + +This approach allows the key storage to be architected more securely than simply storing and loading private keys from +a regular database. +Of course, security is directly dependent on the concrete implementation, +which is why we provide [Stronghold](https://github.com/iotaledger/stronghold.rs/), a best-effort in-software enclave, by default. + +However, there are cases where one cannot use `Stronghold`, +or may want to integrate key management of identities into their own KMS or similar, +which is why the key storage is an abstraction over such systems. +Any implementation of a key storage can be used by the `JwkDocumentExt` API. + +The two interfaces making up the key storage have two respective responsibilities. + +:::info + +Even though there are two separate interfaces, you can implement them using the same backing storage, if desired. + +::: + +## Function Overview + +A brief overview of those functions: + +- `JwkStorage`: CRUD and signing operations on [JSON Web Keys](https://www.rfc-editor.org/rfc/rfc7517). + - `generate`: Generate a new key represented as a JSON Web Key. + - `insert`: Insert an existing JSON Web Key into the storage. + - `sign`: Signs the provided data using the stored private key. + - `delete`: Permanently deletes a key. + - `exists`: Returns whether a key exists. +- `KeyIdStorage`: Stores the mappings from verification methods to their corresponding key identifier in the `JwkStorage`. + - `insert_key_id`: Inserts a mapping from a verification method identifier to a key identifier. + - `get_key_id`: Returns the key identifier for a given verification method identifier. + - `delete_key_id`: Deletes a mapping. + +## Key Identifier + +A `JwkStorage` stores and operates on keys, so they must be identified. +In general, Key Management Systems use some form of an identifier for their keys. +To abstract over those, the `JwkStorage` interface has a general-purpose `KeyId` type, +which is effectively a wrapper around a string. + +A `KeyIdStorage` is needed to store the key id that represents the private key for a given verification method. +To that end, a verification method itself must be identified. + +While within a document, each fragment must be unique, the same is not true given multiple documents, +so we cannot rely only on fragments if we don't want to partition the `KeyIdStorage` by DID. +The solution to this is using a `MethodDigest`, a hash over a verification method. + +When following best security practices, each verification method has its own key associated, and thus a unique public key. +That, plus the fragment of a method ensures the `MethodDigest` is unique. + +So in essence, a `JwkStorage` stores a `KeyId -> JWK` mapping while a `KeyIdStorage` stores a `MethodDigest -> KeyId` mapping. + +:::caution + +Given the construction and limitations of the method digest, +no two documents should contain a method that shares both the same fragment and public key. +This should not happen under typical circumstances, but is good to keep in mind. + +::: + +## Key Types + +To express what key types a given `JwkStorage` implementation supports, you should use the `KeyType`, +which is another simple wrapper around a string. + +The reason for this design might seem odd in Rust, given the existence of associated types. +This more simplistic design is necessary to accommodate implementing the interface via the bindings to the library. + +Implementations are expected to export constants of the key types they support, +so users have an easy way to discover the supported types. +In general, storage implementations are free to support any [JSON Web Algorithm](https://www.rfc-editor.org/rfc/rfc7518.html)-compatible key. +However, the recommended default used by IOTA Identity is the `EdDSA` algorithm with curve `Ed25519`. + +## Implementation + +The IOTA Identity library ships two implementations of key storage. +The `JwkMemStore` and `KeyIdMemstore` are insecure in-memory implementations +intended as example implementations and for testing. + +The default key storage implementation is `Stronghold`, +which is an example of a storage that implements both storage interfaces simultaneously. +[`Stronghold`](https://github.com/iotaledger/stronghold.rs/) may be interesting for implementers to look at, +as it needs to deal with some challenges the in-memory version does not have to deal with. Note that the `Stronghold` implementation is only available in Rust. + +## Examples + +This section shows the Rust and TypeScript `Memstore` implementations. + +### `JwkMemStore` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/jwk_storage.ts +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_storage/memstore.rs +``` + + + + +### `KeyIdMemstore` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/key_id_storage.ts +``` + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_id_storage/memstore.rs +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx new file mode 100644 index 00000000000..4d3ba898da4 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx @@ -0,0 +1,160 @@ +--- +title: Create a Verifiable Credential +sidebar_label: Create and Sign +description: Explain how a VC is created and verified +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - Create + - sign +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +A [verifiable credential (VC)](./../../explanations/verifiable-credentials.mdx) can represent all +information that a physical credential represents, such as a passport or university +degree. However, by allowing other parties to cryptographically verify the authorship +and integrity of the claims, verifiable credentials can be seen as more tamper-evident +and more trustworthy than their physical counterparts. + +## Verifiable Credential Properties + +In the IOTA Identity Framework, you can create a Verifiable Credential with the following properties: + +- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): List of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. +- [**Types**](https://www.w3.org/TR/vc-data-model/#types): List of types describing the credential. Includes `"VerifiableCredential"` by default. +- [**Subject**](https://www.w3.org/TR/vc-data-model/#credential-subject): The issuer's claims; a set of objects that contain one or more properties that are each related to a subject. +- [**Issuer**](https://www.w3.org/TR/vc-data-model/#issuer): The identifier of the issuer, typically their [DID](../../explanations/decentralized-identifiers.mdx). +- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): Optional URI identifier for the credential. +- [**Issuance Date**](https://www.w3.org/TR/vc-data-model/#issuance-date): Timestamp for expressing the date and time when a credential becomes valid. +- [**Expiration Date**](https://www.w3.org/TR/vc-data-model/#expiration): Optional timestamp for expressing the date and time when a credential ceases to be valid. +- [**Status**](https://www.w3.org/TR/vc-data-model/#status): Optional information used to determine the current status of a credential, i.e. whether or not it has been [revoked](./revocation.mdx). +- [**Schema**](https://www.w3.org/TR/vc-data-model/#data-schemas): Optional list of objects specifying the schema that the data must conform to. +- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): Optional link to a service where the recipient may refresh the included credentials. +- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): Optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. +- [**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. + +Other metadata fields such as `challenge` and `domain` may be included, however they are more pertinent for [verifiable presentations](./../../explanations/verifiable-presentations.mdx). + +## Validation + +Verifiers should ensure certain properties of a credential are valid when receiving one or more in a [verifiable presentation](./../../explanations/verifiable-presentations.mdx). Both issuers and holders may also wish to validate their credentials, particularly directly after creating or receiving one. Validation may be performed at any point in time and can be a useful way of checking whether a credential has expired or been revoked. + +### Validation Checks + +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. +- **Optional validations**: Additional checks on credential properties, and the signature can be configured by specifying [Validation Options](#validation-options). + +### Validation Options + +These options specify conditions that specific properties in a credential must satisfy. + +- **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). + +## Sharing Verifiable Credentials + +A [verifiable presentation](./../../explanations/verifiable-presentations.mdx) is the recommended data format for sharing one or more verifiable credentials, +as it provides cryptographic means of proving the DID of the holder presenting them, +and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships). + +## Example + +The following code showcases how an issuer can [create, sign](#create-and-sign-vc), +and [validate](#validate-a-vc) a verifiable credential. +In this example, the issuer signs a `UniversityDegreeCredential` with Alice's name and DID. + +### Create and Sign a VC + + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L67-L98 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74 +``` + + + +
+ +### Validate a VC + +
+ + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs#L105-L113 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88 +``` + + + +
+ +This Verifiable Credential can be [verified by anyone](./../../explanations/verifiable-presentations.mdx), +allowing Alice to take control of it and share it with anyone. + +### Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/5_create_vc.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/5_create_vc.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx new file mode 100644 index 00000000000..51efdcd78ee --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx @@ -0,0 +1,129 @@ +--- +sidebar_label: Revoke +description: Explain how a VC can be revoked +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - revoke + - revocation +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Revoke a Verifiable Credential + +The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential +using the IOTA Identity Framework: + +1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking to a +[revocation bitmap](#revocation-bitmap), +using the [`RevocationBitmap2022`](/identity.rs/references/specifications/revocation-bitmap-2022/). +2. By [removing the verification method](#removing-the-verification-method) that signed the credential. +This invalidates all credentials that were signed with that verification method. + +## Revocation Bitmap + + +One of the ways for an issuer to control the status of its credentials is by using a revocation list. +At the most basic level, revocation information for all verifiable credentials issued by an issuer are expressed as +simple binary values. +The issuer keeps a list of all verifiable credentials it has issued in a bitmap. +Each verifiable credential is associated with a unique index in the list. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L167 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 +``` + + + + +If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, +if it is 0 (zero) it is not revoked. + +For example, with this approach the issuer adds an index to a credential in the `credentialStatus` field, such as `"5"`. +This part of the credential might then look like this: + +```json +"credentialStatus": { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "revocationBitmapIndex": "5" +}, +``` + +The verifier uses the `id` field (`did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation`) to look up the +service in the issuer's DID document: + +```json +{ + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" +} +``` + +During verification, the verifier decodes the revocation bitmap embedded in the `data` url. +This bitmap written as a bitstring looks like this: `000001`. +Here, the 5th bit is set, which means the credential with that index is revoked, +while all other credentials aren't revoked. + +## Removing the Verification Method + +A less efficient alternative is to remove the verification method that signed the credential from the DID Document of +the issuer. +This means the VC can no longer be validated. + +However, this will also invalidate every VC signed with that verification method, +meaning that the issuer will have to sign every VC with a different key to retain +precise control over which credential is revoked. + + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L197-L204 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 +``` + + + + +## Full Example Code + +The following code exemplifies how you can revoke a [Verifiable Credential (VC)](../../explanations/verifiable-credentials.mdx). + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx new file mode 100644 index 00000000000..7ae2620df99 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -0,0 +1,164 @@ +--- +sidebar_label: Create and Validate +description: Explain how a VP is created and verified +image: /img/Identity_icon.png +keywords: + - verifiable + - presentations +--- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Create and Validate Verifiable Presentations + +The IOTA Identity Framework enables holders tos easily construct +[verifiable presentations](./../../explanations/verifiable-presentations.mdx). +As demonstrated in the [example](#example), +holders only need to pass in their credentials to present and sign the presentation. + +## Properties + +You can specify the following properties in a presentation: + +- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): Optional URI identifier for the presentation. +- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): List of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. +- [**Types**](https://www.w3.org/TR/vc-data-model/#types): List of types describing the presentation. Includes `"VerifiablePresentation"` by default. +- [**Credentials**](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials): List of verifiable credentials to present. +- [**Holder**](https://www.w3.org/TR/vc-data-model/#dfn-holders): Optional URI, typically a DID, of the entity that generated the presentation. +- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): Optional link to a service where the recipient may refresh the included credentials. +- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): Optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. + +Of the above, **only the list of credentials is required** when creating a presentation using the framework. +However, the holder property should be included to satisfy [subject-holder relationship](#subject-holder-relationship) checks during validation. + +After creation, the holder signs the verifiable presentation using a private key linked to one of the verification +methods in their DID Document and transmits it to a verifier for validation. + +## Proof Options + +A digital signature on a verifiable presentation provides data integrity, +and also proves the [DID](../../explanations/decentralized-identifiers.mdx) of the holder. + +### Metadata Properties + +The proof section embedded in a presentation 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 presentation was signed. +- **Expires**: Timestamp after which the presentation is no longer considered valid. +- **Challenge**: Arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request. +- **Domain**: Arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge. +- **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. + +:::note + +Verifiers should always send a challenge and domain +to [mitigate replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations). + +::: + +A verifier could also choose to ignore some or all of these options. +See [Proof Verifier Options](#proof-verifier-options) for more information. + +## Validation + +The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. +See the [example](#example) for a demonstration of how to validate a presentation. + +The framework checks: + +- **Semantic structure**: Ensures the presentation and its credentials adhere to the specification. +- **Presentation proof**: Verifies the presentation signature against the DID Document of the holder. +- **Credential proofs**: Verifies the credential signatures against the DID Documents of their respective issuers. +- **Optional validations**: Additional checks on signatures and credential fields can be configured by the verifier. + +Note that a verifier may specify which DID Documents to use for the holder and issuers. +Otherwise, they are resolved from the Tangle automatically. + +Currently, the following are **not** checked automatically: + +- **Data schemas**: Credentials that specify a [schema](https://www.w3.org/TR/vc-data-model/#data-schemas) property +should be examined to ensure conformance. +- **Fitness for purpose**: Whether the credentials in a presentation and the data within them are acceptable and +valid depends on the context in which they are used. Verifiers should ensure that the credential types, subjects, +and schemas sent by a holder match what was requested. +- **Issuer trustworthiness**: Verifiers must check that they trust the issuer on each individual credential in a +presentation. The framework only verifies that the issuer's signature on each credential is current and valid +against the given options. + +The default validation behavior may be modified by the following options. + +### Proof Verifier Options + +While the framework always verifies that the digital signature on a verifiable presentation is valid, +a verifier may validate additional fields in the proof on a presentation. +Notably, to mitigate potential [replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations), +a verifier should always check that the challenge and domain fields match what was sent to the holder when +requesting the presentation. + +The following options are available: + +- **Method Scope**: check the signing verification method has a particular [verification relationship](https://www.w3.org/TR/did-core/#verification-relationships). Overridden by the proof purpose check. +- **Method Type**: check the signing verification method has a particular type. +- **Challenge**: check the challenge field matches this string. +- **Domain**: check the domain field matches this string. +- **Proof Purpose**: require a specific purpose on the proof. See [Proof Options](#proof-options). +- **Allow Expired**: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs. + +See [Proof Options](#proof-options) for more information on setting these properties as a holder when signing a verifiable presentation. + +## Subject-Holder Relationship + +Specifies the expected relationship between the holder that signed the verifiable presentation and the subject +specified in each [verifiable credential](./../../explanations/verifiable-credentials.mdx). +This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, +which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. + +By default, the framework always enforces that the holder matches the subject on all credentials. + +The following options are available to modify that behavior: + +- **`AlwaysSubject` (default)**: The holder DID that signed the presentation must match the [`credentialSubject` `id`](https://www.w3.org/TR/vc-data-model/#credential-subject) field in each of the attached credentials. This is the safest option which ensures holders may only present credentials that were directly issued to their DID. An error is thrown on a mismatch or if no subject `id` is present. +- **`SubjectOnNonTransferable`**: The holder DID must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. This is appropriate for accepting [bearer credentials](https://www.w3.org/TR/vc-data-model/#bearer-credentials) while still adhering to the specification. +- **`Any`**: The holder DID is not required to have any kind of relationship to any credential subject. This option performs no checks and ignores the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. + +:::note + +See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) +for further discussion on the different subject-holder relationships. + +::: + +### Credential Validation Options + +These options specify conditions that all credentials in a verifiable presentation must satisfy. + +- **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 the [`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**: See [Proof Verifier Options](#proof-verifier-options) for details. + +## Example Code + +The following code demonstrates how to use the IOTA Identity Framework end-to-end to create and sign a verifiable +presentation as a holder, serialize it to JSON for transmission, deserialize it on the receiving side as a verifier, +and finally validate it with various options. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/6_create_vp.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/6_create_vp.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/docs/references/api/wasm.mdx b/docs/build/identity.rs/1.1/docs/references/api/wasm.mdx new file mode 100644 index 00000000000..c3f1323dcf0 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/api/wasm.mdx @@ -0,0 +1,6251 @@ +--- +title: WASM API Reference +description: WASM API reference. +image: /img/Identity_icon.png +keywords: + - WASM + - API Reference +--- +# Wasm Api Reference + +## Classes + +
+
+ CoreDID +
+
+

A method-agnostic Decentralized Identifier (DID).

+
+
+ CoreDocument +
+
+

A method-agnostic DID Document.

+
+
+ Credential +
+
+
+ DIDUrl +
+
+

A method agnostic DID Url.

+
+
+ DecodedJws +
+
+

A cryptographically verified decoded token from a JWS.

+

Contains the decoded headers and the raw claims.

+
+
+ DecodedJwtCredential +
+
+

A cryptographically verified and decoded Credential.

+

+ Note that having an instance of this type only means the JWS it was + constructed from was verified. It does not imply anything about a + potentially present proof property on the credential itself. +

+
+
+ DecodedJwtPresentation +
+
+

A cryptographically verified and decoded presentation.

+

+ Note that having an instance of this type only means the JWS it was + constructed from was verified. It does not imply anything about a + potentially present proof property on the presentation itself. +

+
+
+ DomainLinkageConfiguration +
+
+

+ DID Configuration Resource which contains Domain Linkage Credentials. It + can be placed in an origin's .well-known directory to + prove linkage between the origin and a DID. See:{' '} + + https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource + +

+

Note:

+ +
+
+ Duration +
+
+

A span of time.

+
+
+ EdDSAJwsVerifier +
+
+

+ An implementor of `IJwsVerifier` that can handle the + EdDSA algorithm. +

+
+
+ IotaDID +
+
+

A DID conforming to the IOTA DID method specification.

+
+
+ IotaDocument +
+
+
+ IotaDocumentMetadata +
+
+

Additional attributes related to an IOTA DID Document.

+
+
+ IotaIdentityClientExt +
+
+

+ An extension interface that provides helper functions for publication and + resolution of DID documents in Alias Outputs. +

+
+
+ Jwk +
+
+
+ JwkGenOutput +
+
+

+ The result of a key generation in JwkStorage. +

+
+
+ Jws +
+
+

A wrapper around a JSON Web Signature (JWS).

+
+
+ JwsHeader +
+
+
+ JwsSignatureOptions +
+
+
+ JwsVerificationOptions +
+
+
+ Jwt +
+
+

A wrapper around a JSON Web Token (JWK).

+
+
+ JwtCredentialValidationOptions +
+
+

Options to declare validation criteria when validating credentials.

+
+
+ JwtCredentialValidator +
+
+

+ A type for decoding and validating Credential. +

+
+
+ JwtDomainLinkageValidator +
+
+

A validator for a Domain Linkage Configuration and Credentials.

+
+
+ JwtPresentationOptions +
+
+
+ + JwtPresentationValidationOptions + +
+
+

Options to declare validation criteria when validating presentation.

+
+
+ JwtPresentationValidator +
+
+
+ LinkedDomainService +
+
+
+ MethodData +
+
+

Supported verification method data formats.

+
+
+ MethodDigest +
+
+

+ Unique identifier of a{' '} + VerificationMethod. +

+

+ NOTE: This class does not have a JSON representation, use the methods{' '} + pack and unpack instead. +

+
+
+ MethodScope +
+
+

Supported verification method types.

+
+
+ MethodType +
+
+

Supported verification method types.

+
+
+ Presentation +
+
+
+ Proof +
+
+

+ Represents a cryptographic proof that can be used to validate verifiable + credentials and presentations. +

+

+ This representation does not inherently implement any standard; instead, + it can be utilized to implement standards or user-defined proofs. The + presence of the + type field is necessary to accommodate different types of cryptographic + proofs. +

+

+ Note that this proof is not related to JWT and can be used in combination + or as an alternative to it. +

+
+
+ Resolver +
+
+

+ Convenience type for resolving DID documents from different DID methods. +

+

+ Also provides methods for resolving DID Documents associated with + verifiable Credentials and{' '} + Presentations. +

+

Configuration

+

+ The resolver will only be able to resolve DID documents for methods it has + been configured for in the constructor. +

+
+
+ RevocationBitmap +
+
+

A compressed bitmap for managing credential revocation.

+
+
+ Service +
+
+

+ A DID Document Service used to enable trusted interactions associated with + a DID subject. +

+
+
+ Storage +
+
+

+ A type wrapping a JwkStorage and KeyIdStorage{' '} + that should always be used together when working with storage backed DID + documents. +

+
+
+ Timestamp +
+
+
+ UnknownCredential +
+
+
+ VerificationMethod +
+
+

A DID Document Verification Method.

+
+
+ +## Members + +
+
+ StatusCheck +
+
+

+ Controls validation behaviour when checking whether or not a credential + has been revoked by its + + credentialStatus + . +

+
+
+ Strict +
+
+

+ Validate the status if supported, reject any unsupported + + credentialStatus + types. +

+

+ Only RevocationBitmap2022 is currently supported. +

+

This is the default.

+
+
+ SkipUnsupported +
+
+

+ Validate the status if supported, skip any unsupported + + credentialStatus + types. +

+
+
+ SkipAll +
+
+

Skip all status checks.

+
+
+ SubjectHolderRelationship +
+
+

+ Declares how credential subjects must relate to the presentation holder. +

+

+ See also the{' '} + + Subject-Holder Relationship + {' '} + section of the specification. +

+
+
+ AlwaysSubject +
+
+

+ The holder must always match the subject on all credentials, regardless of + their{' '} + + nonTransferable + {' '} + property. This variant is the default. +

+
+
+ SubjectOnNonTransferable +
+
+

+ The holder must match the subject only for credentials where the{' '} + + nonTransferable + {' '} + property is true. +

+
+
+ Any +
+
+

+ The holder is not required to have any kind of relationship to any + credential subject. +

+
+
+ FailFast +
+
+

Declares when validation should return if an error occurs.

+
+
+ AllErrors +
+
+

Return all errors that occur during validation.

+
+
+ FirstError +
+
+

Return after the first error occurs.

+
+
+ StateMetadataEncoding +
+
+
+ MethodRelationship +
+
+
+ +## Functions + +
+
+ + verifyEd25519(alg, signingInput, decodedSignature, publicKey) + +
+
+

+ Verify a JWS signature secured with the EdDSA algorithm and + curve Ed25519. +

+

+ This function is useful when one is composing a `IJwsVerifier` that + delegates + EdDSA verification with curve Ed25519 to this function. +

+

Warning

+

+ This function does not check whether alg = EdDSA in the + protected header. Callers are expected to assert this prior to calling the + function. +

+
+
+ start() +
+
+

Initializes the console error panic hook for better error messages

+
+
+ encodeB64(data) ⇒ string +
+
+

Encode the given bytes in url-safe base64.

+
+
+ decodeB64(data) ⇒ Uint8Array +
+
+

Decode the given url-safe base64-encoded slice into its raw bytes.

+
+
+ + + +## CoreDID + +A method-agnostic Decentralized Identifier (DID). + +**Kind**: global class + +- [CoreDID](#CoreDID) + - _instance_ + - [.setMethodName(value)](#CoreDID+setMethodName) + - [.setMethodId(value)](#CoreDID+setMethodId) + - [.scheme()](#CoreDID+scheme) ⇒ string + - [.authority()](#CoreDID+authority) ⇒ string + - [.method()](#CoreDID+method) ⇒ string + - [.methodId()](#CoreDID+methodId) ⇒ string + - [.join(segment)](#CoreDID+join) ⇒ [DIDUrl](#DIDUrl) + - [.toUrl()](#CoreDID+toUrl) ⇒ [DIDUrl](#DIDUrl) + - [.intoUrl()](#CoreDID+intoUrl) ⇒ [DIDUrl](#DIDUrl) + - [.toString()](#CoreDID+toString) ⇒ string + - [.toCoreDid()](#CoreDID+toCoreDid) ⇒ [CoreDID](#CoreDID) + - [.toJSON()](#CoreDID+toJSON) ⇒ any + - [.clone()](#CoreDID+clone) ⇒ [CoreDID](#CoreDID) + - _static_ + - [.parse(input)](#CoreDID.parse) ⇒ [CoreDID](#CoreDID) + - [.validMethodName(value)](#CoreDID.validMethodName) ⇒ boolean + - [.validMethodId(value)](#CoreDID.validMethodId) ⇒ boolean + - [.fromJSON(json)](#CoreDID.fromJSON) ⇒ [CoreDID](#CoreDID) + + + +### coreDID.setMethodName(value) + +Set the method name of the [CoreDID](#CoreDID). + +**Kind**: instance method of [CoreDID](#CoreDID) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### coreDID.setMethodId(value) + +Set the method-specific-id of the `DID`. + +**Kind**: instance method of [CoreDID](#CoreDID) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### coreDID.scheme() ⇒ string + +Returns the [CoreDID](#CoreDID) scheme. + +E.g. + +- `"did:example:12345678" -> "did"` +- `"did:iota:smr:12345678" -> "did"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.authority() ⇒ string + +Returns the [CoreDID](#CoreDID) authority: the method name and method-id. + +E.g. + +- `"did:example:12345678" -> "example:12345678"` +- `"did:iota:smr:12345678" -> "iota:smr:12345678"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.method() ⇒ string + +Returns the [CoreDID](#CoreDID) method name. + +E.g. + +- `"did:example:12345678" -> "example"` +- `"did:iota:smr:12345678" -> "iota"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.methodId() ⇒ string + +Returns the [CoreDID](#CoreDID) method-specific ID. + +E.g. + +- `"did:example:12345678" -> "12345678"` +- `"did:iota:smr:12345678" -> "smr:12345678"` + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.join(segment) ⇒ [DIDUrl](#DIDUrl) + +Construct a new [DIDUrl](#DIDUrl) by joining with a relative DID Url string. + +**Kind**: instance method of [CoreDID](#CoreDID) + +| Param | Type | +| ------- | ------------------- | +| segment | string | + + + +### coreDID.toUrl() ⇒ [DIDUrl](#DIDUrl) + +Clones the [CoreDID](#CoreDID) into a [DIDUrl](#DIDUrl). + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.intoUrl() ⇒ [DIDUrl](#DIDUrl) + +Converts the [CoreDID](#CoreDID) into a [DIDUrl](#DIDUrl), consuming it. + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.toString() ⇒ string + +Returns the [CoreDID](#CoreDID) as a string. + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.toCoreDid() ⇒ [CoreDID](#CoreDID) + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### coreDID.clone() ⇒ [CoreDID](#CoreDID) + +Deep clones the object. + +**Kind**: instance method of [CoreDID](#CoreDID) + + + +### CoreDID.parse(input) ⇒ [CoreDID](#CoreDID) + +Parses a [CoreDID](#CoreDID) from the given `input`. + +### Errors + +Throws an error if the input is not a valid [CoreDID](#CoreDID). + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| ----- | ------------------- | +| input | string | + + + +### CoreDID.validMethodName(value) ⇒ boolean + +Validates whether a string is a valid DID method name. + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### CoreDID.validMethodId(value) ⇒ boolean + +Validates whether a string is a valid `DID` method-id. + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### CoreDID.fromJSON(json) ⇒ [CoreDID](#CoreDID) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [CoreDID](#CoreDID) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## CoreDocument + +A method-agnostic DID Document. + +**Kind**: global class + +- [CoreDocument](#CoreDocument) + - [new CoreDocument(values)](#new_CoreDocument_new) + - _instance_ + - [.id()](#CoreDocument+id) ⇒ [CoreDID](#CoreDID) + - [.setId(id)](#CoreDocument+setId) + - [.controller()](#CoreDocument+controller) ⇒ [Array.<CoreDID>](#CoreDID) + - [.setController(controllers)](#CoreDocument+setController) + - [.alsoKnownAs()](#CoreDocument+alsoKnownAs) ⇒ Array.<string> + - [.setAlsoKnownAs(urls)](#CoreDocument+setAlsoKnownAs) + - [.verificationMethod()](#CoreDocument+verificationMethod) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + - [.authentication()](#CoreDocument+authentication) ⇒ Array.<(DIDUrl\|VerificationMethod)> + - [.assertionMethod()](#CoreDocument+assertionMethod) ⇒ Array.<(DIDUrl\|VerificationMethod)> + - [.keyAgreement()](#CoreDocument+keyAgreement) ⇒ Array.<(DIDUrl\|VerificationMethod)> + - [.capabilityDelegation()](#CoreDocument+capabilityDelegation) ⇒ Array.<(DIDUrl\|VerificationMethod)> + - [.capabilityInvocation()](#CoreDocument+capabilityInvocation) ⇒ Array.<(DIDUrl\|VerificationMethod)> + - [.properties()](#CoreDocument+properties) ⇒ Map.<string, any> + - [.setPropertyUnchecked(key, value)](#CoreDocument+setPropertyUnchecked) + - [.service()](#CoreDocument+service) ⇒ [Array.<Service>](#Service) + - [.insertService(service)](#CoreDocument+insertService) + - [.removeService(didUrl)](#CoreDocument+removeService) ⇒ [Service](#Service) \| undefined + - [.resolveService(query)](#CoreDocument+resolveService) ⇒ [Service](#Service) \| undefined + - [.methods(scope)](#CoreDocument+methods) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + - [.verificationRelationships()](#CoreDocument+verificationRelationships) ⇒ Array.<(DIDUrl\|VerificationMethod)> + - [.insertMethod(method, scope)](#CoreDocument+insertMethod) + - [.removeMethod(did)](#CoreDocument+removeMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + - [.resolveMethod(query, scope)](#CoreDocument+resolveMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + - [.attachMethodRelationship(didUrl, relationship)](#CoreDocument+attachMethodRelationship) ⇒ boolean + - [.detachMethodRelationship(didUrl, relationship)](#CoreDocument+detachMethodRelationship) ⇒ boolean + - [.verifyJws(jws, options, signatureVerifier, detachedPayload)](#CoreDocument+verifyJws) ⇒ [DecodedJws](#DecodedJws) + - [.revokeCredentials(serviceQuery, indices)](#CoreDocument+revokeCredentials) + - [.unrevokeCredentials(serviceQuery, indices)](#CoreDocument+unrevokeCredentials) + - [.clone()](#CoreDocument+clone) ⇒ [CoreDocument](#CoreDocument) + - [.\_shallowCloneInternal()](#CoreDocument+_shallowCloneInternal) ⇒ [CoreDocument](#CoreDocument) + - [.\_strongCountInternal()](#CoreDocument+_strongCountInternal) ⇒ number + - [.toJSON()](#CoreDocument+toJSON) ⇒ any + - [.generateMethod(storage, keyType, alg, fragment, scope)](#CoreDocument+generateMethod) ⇒ Promise.<string> + - [.purgeMethod(storage, id)](#CoreDocument+purgeMethod) ⇒ Promise.<void> + - [.createJws(storage, fragment, payload, options)](#CoreDocument+createJws) ⇒ [Promise.<Jws>](#Jws) + - [.createCredentialJwt(storage, fragment, credential, options, custom_claims)](#CoreDocument+createCredentialJwt) ⇒ [Promise.<Jwt>](#Jwt) + - [.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options)](#CoreDocument+createPresentationJwt) ⇒ [Promise.<Jwt>](#Jwt) + - _static_ + - [.fromJSON(json)](#CoreDocument.fromJSON) ⇒ [CoreDocument](#CoreDocument) + + + +### new CoreDocument(values) + +Creates a new [CoreDocument](#CoreDocument) with the given properties. + +| Param | Type | +| ------ | -------------------------- | +| values | ICoreDocument | + + + +### coreDocument.id() ⇒ [CoreDID](#CoreDID) + +Returns a copy of the DID Document `id`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.setId(id) + +Sets the DID of the document. + +### Warning + +Changing the identifier can drastically alter the results of +`resolve_method`, `resolve_service` and the related +[DID URL dereferencing](https://w3c-ccg.github.io/did-resolution/#dereferencing) algorithm. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | -------------------------------- | +| id | [CoreDID](#CoreDID) | + + + +### coreDocument.controller() ⇒ [Array.<CoreDID>](#CoreDID) + +Returns a copy of the document controllers. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.setController(controllers) + +Sets the controllers of the DID Document. + +Note: Duplicates will be ignored. +Use `null` to remove all controllers. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----------- | ------------------------------------------------------------------------------------------------------- | +| controllers | [CoreDID](#CoreDID) \| [Array.<CoreDID>](#CoreDID) \| null | + + + +### coreDocument.alsoKnownAs() ⇒ Array.<string> + +Returns a copy of the document's `alsoKnownAs` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.setAlsoKnownAs(urls) + +Sets the `alsoKnownAs` property in the DID document. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | ----------------------------------------------------------------------------- | +| urls | string \| Array.<string> \| null | + + + +### coreDocument.verificationMethod() ⇒ [Array.<VerificationMethod>](#VerificationMethod) + +Returns a copy of the document's `verificationMethod` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.authentication() ⇒ Array.<(DIDUrl\|VerificationMethod)> + +Returns a copy of the document's `authentication` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.assertionMethod() ⇒ Array.<(DIDUrl\|VerificationMethod)> + +Returns a copy of the document's `assertionMethod` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.keyAgreement() ⇒ Array.<(DIDUrl\|VerificationMethod)> + +Returns a copy of the document's `keyAgreement` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.capabilityDelegation() ⇒ Array.<(DIDUrl\|VerificationMethod)> + +Returns a copy of the document's `capabilityDelegation` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.capabilityInvocation() ⇒ Array.<(DIDUrl\|VerificationMethod)> + +Returns a copy of the document's `capabilityInvocation` set. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.properties() ⇒ Map.<string, any> + +Returns a copy of the custom DID Document properties. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.setPropertyUnchecked(key, value) + +Sets a custom property in the DID Document. +If the value is set to `null`, the custom property will be removed. + +### WARNING + +This method can overwrite existing properties like `id` and result in an invalid document. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | ------------------- | +| key | string | +| value | any | + + + +### coreDocument.service() ⇒ [Array.<Service>](#Service) + +Returns a set of all [Service](#Service) in the document. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.insertService(service) + +Add a new [Service](#Service) to the document. + +Errors if there already exists a service or verification method with the same id. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------- | -------------------------------- | +| service | [Service](#Service) | + + + +### coreDocument.removeService(didUrl) ⇒ [Service](#Service) \| undefined + +Remove a [Service](#Service) identified by the given [DIDUrl](#DIDUrl) from the document. + +Returns `true` if the service was removed. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------ | ------------------------------ | +| didUrl | [DIDUrl](#DIDUrl) | + + + +### coreDocument.resolveService(query) ⇒ [Service](#Service) \| undefined + +Returns the first [Service](#Service) with an `id` property matching the provided `query`, +if present. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | ----------------------------------------------------- | +| query | [DIDUrl](#DIDUrl) \| string | + + + +### coreDocument.methods(scope) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + +Returns a list of all [VerificationMethod](#VerificationMethod) in the DID Document, +whose verification relationship matches `scope`. + +If `scope` is not set, a list over the **embedded** methods is returned. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | ------------------------------------------------------------------ | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### coreDocument.verificationRelationships() ⇒ Array.<(DIDUrl\|VerificationMethod)> + +Returns an array of all verification relationships. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.insertMethod(method, scope) + +Adds a new `method` to the document in the given `scope`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------ | ------------------------------------------------------ | +| method | [VerificationMethod](#VerificationMethod) | +| scope | [MethodScope](#MethodScope) | + + + +### coreDocument.removeMethod(did) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + +Removes all references to the specified Verification Method. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | ------------------------------ | +| did | [DIDUrl](#DIDUrl) | + + + +### coreDocument.resolveMethod(query, scope) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + +Returns a copy of the first verification method with an `id` property +matching the provided `query` and the verification relationship +specified by `scope`, if present. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | ------------------------------------------------------------------ | +| query | [DIDUrl](#DIDUrl) \| string | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### coreDocument.attachMethodRelationship(didUrl, relationship) ⇒ boolean + +Attaches the relationship to the given method, if the method exists. + +Note: The method needs to be in the set of verification methods, +so it cannot be an embedded one. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------------ | ------------------------------ | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### coreDocument.detachMethodRelationship(didUrl, relationship) ⇒ boolean + +Detaches the given relationship from the given method, if the method exists. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------------ | ------------------------------ | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### coreDocument.verifyJws(jws, options, signatureVerifier, detachedPayload) ⇒ [DecodedJws](#DecodedJws) + +Decodes and verifies the provided JWS according to the passed `options` and `signatureVerifier`. +If no `signatureVerifier` argument is provided a default verifier will be used that is (only) capable of +verifying EdDSA signatures. + +Regardless of which options are passed the following conditions must be met in order for a verification attempt to +take place. + +- The JWS must be encoded according to the JWS compact serialization. +- The `kid` value in the protected header must be an identifier of a verification method in this DID document, + or set explicitly in the `options`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----------------- | -------------------------------------------------------------- | +| jws | [Jws](#Jws) | +| options | [JwsVerificationOptions](#JwsVerificationOptions) | +| signatureVerifier | IJwsVerifier | +| detachedPayload | string \| undefined | + + + +### coreDocument.revokeCredentials(serviceQuery, indices) + +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +revoke all specified `indices`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------------ | -------------------------------------------------------- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### coreDocument.unrevokeCredentials(serviceQuery, indices) + +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +unrevoke all specified `indices`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------------ | -------------------------------------------------------- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### coreDocument.clone() ⇒ [CoreDocument](#CoreDocument) + +Deep clones the [CoreDocument](#CoreDocument). + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.\_shallowCloneInternal() ⇒ [CoreDocument](#CoreDocument) + +### Warning + +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.\_strongCountInternal() ⇒ number + +### Warning + +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.toJSON() ⇒ any + +Serializes to a plain JS representation. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + + + +### coreDocument.generateMethod(storage, keyType, alg, fragment, scope) ⇒ Promise.<string> + +Generate new key material in the given `storage` and insert a new verification method with the corresponding +public key material into the DID document. + +- If no fragment is given the `kid` of the generated JWK is used, if it is set, otherwise an error is returned. +- The `keyType` must be compatible with the given `storage`. `Storage`s are expected to export key type constants + for that use case. + +The fragment of the generated method is returned. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| -------- | --------------------------------------------- | +| storage | [Storage](#Storage) | +| keyType | string | +| alg | JwsAlgorithm | +| fragment | string \| undefined | +| scope | [MethodScope](#MethodScope) | + + + +### coreDocument.purgeMethod(storage, id) ⇒ Promise.<void> + +Remove the method identified by the `fragment` from the document and delete the corresponding key material in +the `storage`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------- | -------------------------------- | +| storage | [Storage](#Storage) | +| id | [DIDUrl](#DIDUrl) | + + + +### coreDocument.createJws(storage, fragment, payload, options) ⇒ [Promise.<Jws>](#Jws) + +Sign the `payload` according to `options` with the storage backed private key corresponding to the public key +material in the verification method identified by the given `fragment. + +Upon success a string representing a JWS encoded according to the Compact JWS Serialization format is returned. +See [RFC7515 section 3.1](https://www.rfc-editor.org/rfc/rfc7515#section-3.1). + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| -------- | -------------------------------------------------------- | +| storage | [Storage](#Storage) | +| fragment | string | +| payload | string | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | + + + +### coreDocument.createCredentialJwt(storage, fragment, credential, options, custom_claims) ⇒ [Promise.<Jwt>](#Jwt) + +Produces a JWT where the payload is produced from the given `credential` +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +The `custom_claims` can be used to set additional claims on the resulting JWT. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ------------- | ----------------------------------------------------------------- | +| storage | [Storage](#Storage) | +| fragment | string | +| credential | [Credential](#Credential) | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | +| custom_claims | Record.<string, any> \| undefined | + + + +### coreDocument.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options) ⇒ [Promise.<Jwt>](#Jwt) + +Produces a JWT where the payload is produced from the given presentation. +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +**Kind**: instance method of [CoreDocument](#CoreDocument) + +| Param | Type | +| -------------------- | -------------------------------------------------------------- | +| storage | [Storage](#Storage) | +| fragment | string | +| presentation | [Presentation](#Presentation) | +| signature_options | [JwsSignatureOptions](#JwsSignatureOptions) | +| presentation_options | [JwtPresentationOptions](#JwtPresentationOptions) | + + + +### CoreDocument.fromJSON(json) ⇒ [CoreDocument](#CoreDocument) + +Deserializes an instance from a plain JS representation. + +**Kind**: static method of [CoreDocument](#CoreDocument) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## Credential + +**Kind**: global class + +- [Credential](#Credential) + - [new Credential(values)](#new_Credential_new) + - _instance_ + - [.context()](#Credential+context) ⇒ Array.<(string\|Record.<string, any>)> + - [.id()](#Credential+id) ⇒ string \| undefined + - [.type()](#Credential+type) ⇒ Array.<string> + - [.credentialSubject()](#Credential+credentialSubject) ⇒ Array.<Subject> + - [.issuer()](#Credential+issuer) ⇒ string \| Issuer + - [.issuanceDate()](#Credential+issuanceDate) ⇒ [Timestamp](#Timestamp) + - [.expirationDate()](#Credential+expirationDate) ⇒ [Timestamp](#Timestamp) \| undefined + - [.credentialStatus()](#Credential+credentialStatus) ⇒ Array.<Status> + - [.credentialSchema()](#Credential+credentialSchema) ⇒ Array.<Schema> + - [.refreshService()](#Credential+refreshService) ⇒ Array.<RefreshService> + - [.termsOfUse()](#Credential+termsOfUse) ⇒ Array.<Policy> + - [.evidence()](#Credential+evidence) ⇒ Array.<Evidence> + - [.nonTransferable()](#Credential+nonTransferable) ⇒ boolean \| undefined + - [.proof()](#Credential+proof) ⇒ [Proof](#Proof) \| undefined + - [.properties()](#Credential+properties) ⇒ Map.<string, any> + - [.setProof(proof)](#Credential+setProof) + - [.toJSON()](#Credential+toJSON) ⇒ any + - [.clone()](#Credential+clone) ⇒ [Credential](#Credential) + - _static_ + - [.BaseContext()](#Credential.BaseContext) ⇒ string + - [.BaseType()](#Credential.BaseType) ⇒ string + - [.createDomainLinkageCredential(values)](#Credential.createDomainLinkageCredential) ⇒ [Credential](#Credential) + - [.fromJSON(json)](#Credential.fromJSON) ⇒ [Credential](#Credential) + + + +### new Credential(values) + +Constructs a new [Credential](#Credential). + +| Param | Type | +| ------ | ------------------------ | +| values | ICredential | + + + +### credential.context() ⇒ Array.<(string\|Record.<string, any>)> + +Returns a copy of the JSON-LD context(s) applicable to the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.id() ⇒ string \| undefined + +Returns a copy of the unique `URI` identifying the [Credential](#Credential) . + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.type() ⇒ Array.<string> + +Returns a copy of the URIs defining the type of the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.credentialSubject() ⇒ Array.<Subject> + +Returns a copy of the [Credential](#Credential) subject(s). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.issuer() ⇒ string \| Issuer + +Returns a copy of the issuer of the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.issuanceDate() ⇒ [Timestamp](#Timestamp) + +Returns a copy of the timestamp of when the [Credential](#Credential) becomes valid. + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.expirationDate() ⇒ [Timestamp](#Timestamp) \| undefined + +Returns a copy of the timestamp of when the [Credential](#Credential) should no longer be considered valid. + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.credentialStatus() ⇒ Array.<Status> + +Returns a copy of the information used to determine the current status of the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.credentialSchema() ⇒ Array.<Schema> + +Returns a copy of the information used to assist in the enforcement of a specific [Credential](#Credential) structure. + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.refreshService() ⇒ Array.<RefreshService> + +Returns a copy of the service(s) used to refresh an expired [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.termsOfUse() ⇒ Array.<Policy> + +Returns a copy of the terms-of-use specified by the [Credential](#Credential) issuer. + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.evidence() ⇒ Array.<Evidence> + +Returns a copy of the human-readable evidence used to support the claims within the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.nonTransferable() ⇒ boolean \| undefined + +Returns whether or not the [Credential](#Credential) must only be contained within a [Presentation](#Presentation) +with a proof issued from the [Credential](#Credential) subject. + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.proof() ⇒ [Proof](#Proof) \| undefined + +Optional cryptographic proof, unrelated to JWT. + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.properties() ⇒ Map.<string, any> + +Returns a copy of the miscellaneous properties on the [Credential](#Credential). + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.setProof(proof) + +Sets the `proof` property of the [Credential](#Credential). + +Note that this proof is not related to JWT. + +**Kind**: instance method of [Credential](#Credential) + +| Param | Type | +| ----- | ------------------------------------------------------ | +| proof | [Proof](#Proof) \| undefined | + + + +### credential.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Credential](#Credential) + + + +### credential.clone() ⇒ [Credential](#Credential) + +Deep clones the object. + +**Kind**: instance method of [Credential](#Credential) + + + +### Credential.BaseContext() ⇒ string + +Returns the base JSON-LD context. + +**Kind**: static method of [Credential](#Credential) + + + +### Credential.BaseType() ⇒ string + +Returns the base type. + +**Kind**: static method of [Credential](#Credential) + + + +### Credential.createDomainLinkageCredential(values) ⇒ [Credential](#Credential) + +**Kind**: static method of [Credential](#Credential) + +| Param | Type | +| ------ | ------------------------------------- | +| values | IDomainLinkageCredential | + + + +### Credential.fromJSON(json) ⇒ [Credential](#Credential) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Credential](#Credential) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## DIDUrl + +A method agnostic DID Url. + +**Kind**: global class + +- [DIDUrl](#DIDUrl) + - _instance_ + - [.did()](#DIDUrl+did) ⇒ [CoreDID](#CoreDID) + - [.urlStr()](#DIDUrl+urlStr) ⇒ string + - [.fragment()](#DIDUrl+fragment) ⇒ string \| undefined + - [.setFragment(value)](#DIDUrl+setFragment) + - [.path()](#DIDUrl+path) ⇒ string \| undefined + - [.setPath(value)](#DIDUrl+setPath) + - [.query()](#DIDUrl+query) ⇒ string \| undefined + - [.setQuery(value)](#DIDUrl+setQuery) + - [.join(segment)](#DIDUrl+join) ⇒ [DIDUrl](#DIDUrl) + - [.toString()](#DIDUrl+toString) ⇒ string + - [.toJSON()](#DIDUrl+toJSON) ⇒ any + - [.clone()](#DIDUrl+clone) ⇒ [DIDUrl](#DIDUrl) + - _static_ + - [.parse(input)](#DIDUrl.parse) ⇒ [DIDUrl](#DIDUrl) + - [.fromJSON(json)](#DIDUrl.fromJSON) ⇒ [DIDUrl](#DIDUrl) + + + +### didUrl.did() ⇒ [CoreDID](#CoreDID) + +Return a copy of the [CoreDID](#CoreDID) section of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### didUrl.urlStr() ⇒ string + +Return a copy of the relative DID Url as a string, including only the path, query, and fragment. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### didUrl.fragment() ⇒ string \| undefined + +Returns a copy of the [DIDUrl](#DIDUrl) method fragment, if any. Excludes the leading '#'. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### didUrl.setFragment(value) + +Sets the `fragment` component of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| ----- | --------------------------------------------- | +| value | string \| undefined | + + + +### didUrl.path() ⇒ string \| undefined + +Returns a copy of the [DIDUrl](#DIDUrl) path. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### didUrl.setPath(value) + +Sets the `path` component of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| ----- | --------------------------------------------- | +| value | string \| undefined | + + + +### didUrl.query() ⇒ string \| undefined + +Returns a copy of the [DIDUrl](#DIDUrl) method query, if any. Excludes the leading '?'. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### didUrl.setQuery(value) + +Sets the `query` component of the [DIDUrl](#DIDUrl). + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| ----- | --------------------------------------------- | +| value | string \| undefined | + + + +### didUrl.join(segment) ⇒ [DIDUrl](#DIDUrl) + +Append a string representing a path, query, and/or fragment, returning a new [DIDUrl](#DIDUrl). + +Must begin with a valid delimiter character: '/', '?', '#'. Overwrites the existing URL +segment and any following segments in order of path, query, then fragment. + +I.e. + +- joining a path will clear the query and fragment. +- joining a query will clear the fragment. +- joining a fragment will only overwrite the fragment. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + +| Param | Type | +| ------- | ------------------- | +| segment | string | + + + +### didUrl.toString() ⇒ string + +Returns the [DIDUrl](#DIDUrl) as a string. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### didUrl.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### didUrl.clone() ⇒ [DIDUrl](#DIDUrl) + +Deep clones the object. + +**Kind**: instance method of [DIDUrl](#DIDUrl) + + + +### DIDUrl.parse(input) ⇒ [DIDUrl](#DIDUrl) + +Parses a [DIDUrl](#DIDUrl) from the input string. + +**Kind**: static method of [DIDUrl](#DIDUrl) + +| Param | Type | +| ----- | ------------------- | +| input | string | + + + +### DIDUrl.fromJSON(json) ⇒ [DIDUrl](#DIDUrl) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [DIDUrl](#DIDUrl) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## DecodedJws + +A cryptographically verified decoded token from a JWS. + +Contains the decoded headers and the raw claims. + +**Kind**: global class + +- [DecodedJws](#DecodedJws) + - [.claims()](#DecodedJws+claims) ⇒ string + - [.claimsBytes()](#DecodedJws+claimsBytes) ⇒ Uint8Array + - [.protectedHeader()](#DecodedJws+protectedHeader) ⇒ [JwsHeader](#JwsHeader) + - [.clone()](#DecodedJws+clone) ⇒ [DecodedJws](#DecodedJws) + - [.toJSON()](#DecodedJws+toJSON) ⇒ any + + + +### decodedJws.claims() ⇒ string + +Returns a copy of the parsed claims represented as a string. + +# Errors + +An error is thrown if the claims cannot be represented as a string. + +This error can only occur if the Token was decoded from a detached payload. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + + +### decodedJws.claimsBytes() ⇒ Uint8Array + +Return a copy of the parsed claims represented as an array of bytes. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + + +### decodedJws.protectedHeader() ⇒ [JwsHeader](#JwsHeader) + +Returns a copy of the protected header. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + + +### decodedJws.clone() ⇒ [DecodedJws](#DecodedJws) + +Deep clones the object. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + + +### decodedJws.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [DecodedJws](#DecodedJws) + + + +## DecodedJwtCredential + +A cryptographically verified and decoded Credential. + +Note that having an instance of this type only means the JWS it was constructed from was verified. +It does not imply anything about a potentially present proof property on the credential itself. + +**Kind**: global class + +- [DecodedJwtCredential](#DecodedJwtCredential) + - [.credential()](#DecodedJwtCredential+credential) ⇒ [Credential](#Credential) + - [.protectedHeader()](#DecodedJwtCredential+protectedHeader) ⇒ [JwsHeader](#JwsHeader) + - [.customClaims()](#DecodedJwtCredential+customClaims) ⇒ Record.<string, any> \| undefined + - [.intoCredential()](#DecodedJwtCredential+intoCredential) ⇒ [Credential](#Credential) + + + +### decodedJwtCredential.credential() ⇒ [Credential](#Credential) + +Returns a copy of the credential parsed to the [Verifiable Credentials Data model](https://www.w3.org/TR/vc-data-model/). + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + + +### decodedJwtCredential.protectedHeader() ⇒ [JwsHeader](#JwsHeader) + +Returns a copy of the protected header parsed from the decoded JWS. + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + + +### decodedJwtCredential.customClaims() ⇒ Record.<string, any> \| undefined + +The custom claims parsed from the JWT. + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + + +### decodedJwtCredential.intoCredential() ⇒ [Credential](#Credential) + +Consumes the object and returns the decoded credential. + +### Warning + +This destroys the [DecodedJwtCredential](#DecodedJwtCredential) object. + +**Kind**: instance method of [DecodedJwtCredential](#DecodedJwtCredential) + + + +## DecodedJwtPresentation + +A cryptographically verified and decoded presentation. + +Note that having an instance of this type only means the JWS it was constructed from was verified. +It does not imply anything about a potentially present proof property on the presentation itself. + +**Kind**: global class + +- [DecodedJwtPresentation](#DecodedJwtPresentation) + - [.presentation()](#DecodedJwtPresentation+presentation) ⇒ [Presentation](#Presentation) + - [.protectedHeader()](#DecodedJwtPresentation+protectedHeader) ⇒ [JwsHeader](#JwsHeader) + - [.intoPresentation()](#DecodedJwtPresentation+intoPresentation) ⇒ [Presentation](#Presentation) + - [.expirationDate()](#DecodedJwtPresentation+expirationDate) ⇒ [Timestamp](#Timestamp) \| undefined + - [.issuanceDate()](#DecodedJwtPresentation+issuanceDate) ⇒ [Timestamp](#Timestamp) \| undefined + - [.audience()](#DecodedJwtPresentation+audience) ⇒ string \| undefined + - [.customClaims()](#DecodedJwtPresentation+customClaims) ⇒ Record.<string, any> \| undefined + + + +### decodedJwtPresentation.presentation() ⇒ [Presentation](#Presentation) + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + + +### decodedJwtPresentation.protectedHeader() ⇒ [JwsHeader](#JwsHeader) + +Returns a copy of the protected header parsed from the decoded JWS. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + + +### decodedJwtPresentation.intoPresentation() ⇒ [Presentation](#Presentation) + +Consumes the object and returns the decoded presentation. + +### Warning + +This destroys the [DecodedJwtPresentation](#DecodedJwtPresentation) object. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + + +### decodedJwtPresentation.expirationDate() ⇒ [Timestamp](#Timestamp) \| undefined + +The expiration date parsed from the JWT claims. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + + +### decodedJwtPresentation.issuanceDate() ⇒ [Timestamp](#Timestamp) \| undefined + +The issuance date parsed from the JWT claims. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + + +### decodedJwtPresentation.audience() ⇒ string \| undefined + +The `aud` property parsed from JWT claims. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + + +### decodedJwtPresentation.customClaims() ⇒ Record.<string, any> \| undefined + +The custom claims parsed from the JWT. + +**Kind**: instance method of [DecodedJwtPresentation](#DecodedJwtPresentation) + + + +## DomainLinkageConfiguration + +DID Configuration Resource which contains Domain Linkage Credentials. +It can be placed in an origin's `.well-known` directory to prove linkage between the origin and a DID. +See: + +Note: + +- Only the [JSON Web Token Proof Format](https://identity.foundation/.well-known/resources/did-configuration/#json-web-token-proof-format) + +**Kind**: global class + +- [DomainLinkageConfiguration](#DomainLinkageConfiguration) + - [new DomainLinkageConfiguration(linkedDids)](#new_DomainLinkageConfiguration_new) + - _instance_ + - [.linkedDids()](#DomainLinkageConfiguration+linkedDids) ⇒ [Array.<Jwt>](#Jwt) + - [.issuers()](#DomainLinkageConfiguration+issuers) ⇒ [Array.<CoreDID>](#CoreDID) + - [.toJSON()](#DomainLinkageConfiguration+toJSON) ⇒ any + - [.clone()](#DomainLinkageConfiguration+clone) ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) + - _static_ + - [.fromJSON(json)](#DomainLinkageConfiguration.fromJSON) ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + + +### new DomainLinkageConfiguration(linkedDids) + +Constructs a new [DomainLinkageConfiguration](#DomainLinkageConfiguration). + +| Param | Type | +| ---------- | -------------------------------------- | +| linkedDids | [Array.<Jwt>](#Jwt) | + + + +### domainLinkageConfiguration.linkedDids() ⇒ [Array.<Jwt>](#Jwt) + +List of the Domain Linkage Credentials. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + + +### domainLinkageConfiguration.issuers() ⇒ [Array.<CoreDID>](#CoreDID) + +List of the issuers of the Domain Linkage Credentials. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + + +### domainLinkageConfiguration.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + + +### domainLinkageConfiguration.clone() ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) + +Deep clones the object. + +**Kind**: instance method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + + + +### DomainLinkageConfiguration.fromJSON(json) ⇒ [DomainLinkageConfiguration](#DomainLinkageConfiguration) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [DomainLinkageConfiguration](#DomainLinkageConfiguration) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## DomainLinkageValidator + +A validator for a Domain Linkage Configuration and Credentials. + +**Kind**: global class + +- [DomainLinkageValidator](#DomainLinkageValidator) + - [new DomainLinkageValidator(signatureVerifier)](#new_DomainLinkageValidator_new) + - [.validateLinkage(issuer, configuration, domain, options)](#DomainLinkageValidator+validateLinkage) + - [.validateCredential(issuer, credentialJwt, domain, options)](#DomainLinkageValidator+validateCredential) + + + +### new DomainLinkageValidator(signatureVerifier) + +Creates a new `DomainLinkageValidator`. If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + +| Param | Type | +| ----------------- | --------------------------------------------------- | +| signatureVerifier | IJwsVerifier \| undefined | + + + +### domainLinkageValidator.validateLinkage(issuer, configuration, domain, options) + +Validates the linkage between a domain and a DID. +[`DomainLinkageConfiguration`] is validated according to [DID Configuration Resource Verification](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification). + +Linkage is valid if no error is thrown. + +# Note + +- Only the [JSON Web Token Proof Format](https://identity.foundation/.well-known/resources/did-configuration/#json-web-token-proof-format) +- Only the Credential issued by `issuer` is verified. + +# Errors + +- Semantic structure of `configuration` is invalid. +- `configuration` includes multiple credentials issued by `issuer`. +- Validation of the matched Domain Linkage Credential fails. + +**Kind**: instance method of [DomainLinkageValidator](#DomainLinkageValidator) + +| Param | Type | +| ------------- | ------------------------------------------------------------------------------ | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| configuration | [DomainLinkageConfiguration](#DomainLinkageConfiguration) | +| domain | string | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | + + + +### domainLinkageValidator.validateCredential(issuer, credentialJwt, domain, options) + +Validates a [Domain Linkage Credential](https://identity.foundation/.well-known/resources/did-configuration/#domain-linkage-credential). +Error will be thrown in case the validation fails. + +**Kind**: instance method of [DomainLinkageValidator](#DomainLinkageValidator) + +| Param | Type | +| ------------- | ------------------------------------------------------------------------------ | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| credentialJwt | [Jwt](#Jwt) | +| domain | string | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | + + + +## Duration + +A span of time. + +**Kind**: global class + +- [Duration](#Duration) + - _instance_ + - [.toJSON()](#Duration+toJSON) ⇒ any + - _static_ + - [.seconds(seconds)](#Duration.seconds) ⇒ [Duration](#Duration) + - [.minutes(minutes)](#Duration.minutes) ⇒ [Duration](#Duration) + - [.hours(hours)](#Duration.hours) ⇒ [Duration](#Duration) + - [.days(days)](#Duration.days) ⇒ [Duration](#Duration) + - [.weeks(weeks)](#Duration.weeks) ⇒ [Duration](#Duration) + - [.fromJSON(json)](#Duration.fromJSON) ⇒ [Duration](#Duration) + + + +### duration.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Duration](#Duration) + + + +### Duration.seconds(seconds) ⇒ [Duration](#Duration) + +Create a new [Duration](#Duration) with the given number of seconds. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| ------- | ------------------- | +| seconds | number | + + + +### Duration.minutes(minutes) ⇒ [Duration](#Duration) + +Create a new [Duration](#Duration) with the given number of minutes. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| ------- | ------------------- | +| minutes | number | + + + +### Duration.hours(hours) ⇒ [Duration](#Duration) + +Create a new [Duration](#Duration) with the given number of hours. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| ----- | ------------------- | +| hours | number | + + + +### Duration.days(days) ⇒ [Duration](#Duration) + +Create a new [Duration](#Duration) with the given number of days. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| ----- | ------------------- | +| days | number | + + + +### Duration.weeks(weeks) ⇒ [Duration](#Duration) + +Create a new [Duration](#Duration) with the given number of weeks. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| ----- | ------------------- | +| weeks | number | + + + +### Duration.fromJSON(json) ⇒ [Duration](#Duration) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Duration](#Duration) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## EdDSAJwsVerifier + +An implementor of `IJwsVerifier` that can handle the +`EdDSA` algorithm. + +**Kind**: global class + +- [EdDSAJwsVerifier](#EdDSAJwsVerifier) + - [new EdDSAJwsVerifier()](#new_EdDSAJwsVerifier_new) + - [.verify(alg, signingInput, decodedSignature, publicKey)](#EdDSAJwsVerifier+verify) + + + +### new EdDSAJwsVerifier() + +Constructs an EdDSAJwsVerifier. + + + +### edDSAJwsVerifier.verify(alg, signingInput, decodedSignature, publicKey) + +Verify a JWS signature secured with the `EdDSA` algorithm. +Only the `Ed25519` curve is supported for now. + +This function is useful when one is building an `IJwsVerifier` that extends the default provided by +the IOTA Identity Framework. + +# Warning + +This function does not check whether `alg = EdDSA` in the protected header. Callers are expected to assert this +prior to calling the function. + +**Kind**: instance method of [EdDSAJwsVerifier](#EdDSAJwsVerifier) + +| Param | Type | +| ---------------- | ------------------------- | +| alg | JwsAlgorithm | +| signingInput | Uint8Array | +| decodedSignature | Uint8Array | +| publicKey | [Jwk](#Jwk) | + + + +## IotaDID + +A DID conforming to the IOTA DID method specification. + +**Kind**: global class + +- [IotaDID](#IotaDID) + - [new IotaDID(bytes, network)](#new_IotaDID_new) + - _instance_ + - [.network()](#IotaDID+network) ⇒ string + - [.tag()](#IotaDID+tag) ⇒ string + - [.toCoreDid()](#IotaDID+toCoreDid) ⇒ [CoreDID](#CoreDID) + - [.scheme()](#IotaDID+scheme) ⇒ string + - [.authority()](#IotaDID+authority) ⇒ string + - [.method()](#IotaDID+method) ⇒ string + - [.methodId()](#IotaDID+methodId) ⇒ string + - [.join(segment)](#IotaDID+join) ⇒ [DIDUrl](#DIDUrl) + - [.toUrl()](#IotaDID+toUrl) ⇒ [DIDUrl](#DIDUrl) + - [.toAliasId()](#IotaDID+toAliasId) ⇒ string + - [.intoUrl()](#IotaDID+intoUrl) ⇒ [DIDUrl](#DIDUrl) + - [.toString()](#IotaDID+toString) ⇒ string + - [.toJSON()](#IotaDID+toJSON) ⇒ any + - [.clone()](#IotaDID+clone) ⇒ [IotaDID](#IotaDID) + - _static_ + - [.METHOD](#IotaDID.METHOD) ⇒ string + - [.DEFAULT_NETWORK](#IotaDID.DEFAULT_NETWORK) ⇒ string + - [.fromAliasId(aliasId, network)](#IotaDID.fromAliasId) ⇒ [IotaDID](#IotaDID) + - [.placeholder(network)](#IotaDID.placeholder) ⇒ [IotaDID](#IotaDID) + - [.parse(input)](#IotaDID.parse) ⇒ [IotaDID](#IotaDID) + - [.fromJSON(json)](#IotaDID.fromJSON) ⇒ [IotaDID](#IotaDID) + + + +### new IotaDID(bytes, network) + +Constructs a new [IotaDID](#IotaDID) from a byte representation of the tag and the given +network name. + +See also [placeholder](#IotaDID.placeholder). + +| Param | Type | +| ------- | ----------------------- | +| bytes | Uint8Array | +| network | string | + + + +### did.network() ⇒ string + +Returns the Tangle network name of the [IotaDID](#IotaDID). + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.tag() ⇒ string + +Returns a copy of the unique tag of the [IotaDID](#IotaDID). + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.toCoreDid() ⇒ [CoreDID](#CoreDID) + +Returns the DID represented as a [CoreDID](#CoreDID). + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.scheme() ⇒ string + +Returns the `DID` scheme. + +E.g. + +- `"did:example:12345678" -> "did"` +- `"did:iota:main:12345678" -> "did"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.authority() ⇒ string + +Returns the `DID` authority: the method name and method-id. + +E.g. + +- `"did:example:12345678" -> "example:12345678"` +- `"did:iota:main:12345678" -> "iota:main:12345678"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.method() ⇒ string + +Returns the `DID` method name. + +E.g. + +- `"did:example:12345678" -> "example"` +- `"did:iota:main:12345678" -> "iota"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.methodId() ⇒ string + +Returns the `DID` method-specific ID. + +E.g. + +- `"did:example:12345678" -> "12345678"` +- `"did:iota:main:12345678" -> "main:12345678"` + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.join(segment) ⇒ [DIDUrl](#DIDUrl) + +Construct a new [DIDUrl](#DIDUrl) by joining with a relative DID Url string. + +**Kind**: instance method of [IotaDID](#IotaDID) + +| Param | Type | +| ------- | ------------------- | +| segment | string | + + + +### did.toUrl() ⇒ [DIDUrl](#DIDUrl) + +Clones the `DID` into a [DIDUrl](#DIDUrl). + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.toAliasId() ⇒ string + +Returns the hex-encoded AliasId with a '0x' prefix, from the DID tag. + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.intoUrl() ⇒ [DIDUrl](#DIDUrl) + +Converts the `DID` into a [DIDUrl](#DIDUrl), consuming it. + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.toString() ⇒ string + +Returns the `DID` as a string. + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### did.clone() ⇒ [IotaDID](#IotaDID) + +Deep clones the object. + +**Kind**: instance method of [IotaDID](#IotaDID) + + + +### IotaDID.METHOD ⇒ string + +The IOTA DID method name (`"iota"`). + +**Kind**: static property of [IotaDID](#IotaDID) + + + +### IotaDID.DEFAULT_NETWORK ⇒ string + +The default Tangle network (`"iota"`). + +**Kind**: static property of [IotaDID](#IotaDID) + + + +### IotaDID.fromAliasId(aliasId, network) ⇒ [IotaDID](#IotaDID) + +Constructs a new [IotaDID](#IotaDID) from a hex representation of an Alias Id and the given +network name. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| ------- | ------------------- | +| aliasId | string | +| network | string | + + + +### IotaDID.placeholder(network) ⇒ [IotaDID](#IotaDID) + +Creates a new placeholder [IotaDID](#IotaDID) with the given network name. + +E.g. `did:iota:smr:0x0000000000000000000000000000000000000000000000000000000000000000`. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| ------- | ------------------- | +| network | string | + + + +### IotaDID.parse(input) ⇒ [IotaDID](#IotaDID) + +Parses a [IotaDID](#IotaDID) from the input string. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| ----- | ------------------- | +| input | string | + + + +### IotaDID.fromJSON(json) ⇒ [IotaDID](#IotaDID) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [IotaDID](#IotaDID) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## IotaDocument + +**Kind**: global class + +- [IotaDocument](#IotaDocument) + - [new IotaDocument(network)](#new_IotaDocument_new) + - _instance_ + - [.id()](#IotaDocument+id) ⇒ [IotaDID](#IotaDID) + - [.controller()](#IotaDocument+controller) ⇒ [Array.<IotaDID>](#IotaDID) + - [.alsoKnownAs()](#IotaDocument+alsoKnownAs) ⇒ Array.<string> + - [.setAlsoKnownAs(urls)](#IotaDocument+setAlsoKnownAs) + - [.properties()](#IotaDocument+properties) ⇒ Map.<string, any> + - [.setPropertyUnchecked(key, value)](#IotaDocument+setPropertyUnchecked) + - [.service()](#IotaDocument+service) ⇒ [Array.<Service>](#Service) + - [.insertService(service)](#IotaDocument+insertService) + - [.removeService(did)](#IotaDocument+removeService) ⇒ [Service](#Service) \| undefined + - [.resolveService(query)](#IotaDocument+resolveService) ⇒ [Service](#Service) \| undefined + - [.methods(scope)](#IotaDocument+methods) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + - [.insertMethod(method, scope)](#IotaDocument+insertMethod) + - [.removeMethod(did)](#IotaDocument+removeMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + - [.resolveMethod(query, scope)](#IotaDocument+resolveMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + - [.attachMethodRelationship(didUrl, relationship)](#IotaDocument+attachMethodRelationship) ⇒ boolean + - [.detachMethodRelationship(didUrl, relationship)](#IotaDocument+detachMethodRelationship) ⇒ boolean + - [.verifyJws(jws, options, signatureVerifier, detachedPayload)](#IotaDocument+verifyJws) ⇒ [DecodedJws](#DecodedJws) + - [.pack()](#IotaDocument+pack) ⇒ Uint8Array + - [.packWithEncoding(encoding)](#IotaDocument+packWithEncoding) ⇒ Uint8Array + - [.metadata()](#IotaDocument+metadata) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + - [.metadataCreated()](#IotaDocument+metadataCreated) ⇒ [Timestamp](#Timestamp) \| undefined + - [.setMetadataCreated(timestamp)](#IotaDocument+setMetadataCreated) + - [.metadataUpdated()](#IotaDocument+metadataUpdated) ⇒ [Timestamp](#Timestamp) \| undefined + - [.setMetadataUpdated(timestamp)](#IotaDocument+setMetadataUpdated) + - [.metadataDeactivated()](#IotaDocument+metadataDeactivated) ⇒ boolean \| undefined + - [.setMetadataDeactivated(deactivated)](#IotaDocument+setMetadataDeactivated) + - [.metadataStateControllerAddress()](#IotaDocument+metadataStateControllerAddress) ⇒ string \| undefined + - [.metadataGovernorAddress()](#IotaDocument+metadataGovernorAddress) ⇒ string \| undefined + - [.setMetadataPropertyUnchecked(key, value)](#IotaDocument+setMetadataPropertyUnchecked) + - [.revokeCredentials(serviceQuery, indices)](#IotaDocument+revokeCredentials) + - [.unrevokeCredentials(serviceQuery, indices)](#IotaDocument+unrevokeCredentials) + - [.clone()](#IotaDocument+clone) ⇒ [IotaDocument](#IotaDocument) + - [.\_shallowCloneInternal()](#IotaDocument+_shallowCloneInternal) ⇒ [IotaDocument](#IotaDocument) + - [.\_strongCountInternal()](#IotaDocument+_strongCountInternal) ⇒ number + - [.toJSON()](#IotaDocument+toJSON) ⇒ any + - [.toCoreDocument()](#IotaDocument+toCoreDocument) ⇒ [CoreDocument](#CoreDocument) + - [.generateMethod(storage, keyType, alg, fragment, scope)](#IotaDocument+generateMethod) ⇒ Promise.<string> + - [.purgeMethod(storage, id)](#IotaDocument+purgeMethod) ⇒ Promise.<void> + - [.createJwt(storage, fragment, payload, options)](#IotaDocument+createJwt) ⇒ [Promise.<Jws>](#Jws) + - [.createCredentialJwt(storage, fragment, credential, options, custom_claims)](#IotaDocument+createCredentialJwt) ⇒ [Promise.<Jwt>](#Jwt) + - [.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options)](#IotaDocument+createPresentationJwt) ⇒ [Promise.<Jwt>](#Jwt) + - _static_ + - [.newWithId(id)](#IotaDocument.newWithId) ⇒ [IotaDocument](#IotaDocument) + - [.unpackFromOutput(did, aliasOutput, allowEmpty)](#IotaDocument.unpackFromOutput) ⇒ [IotaDocument](#IotaDocument) + - [.unpackFromBlock(network, block)](#IotaDocument.unpackFromBlock) ⇒ [Array.<IotaDocument>](#IotaDocument) + - [.fromJSON(json)](#IotaDocument.fromJSON) ⇒ [IotaDocument](#IotaDocument) + + + +### new IotaDocument(network) + +Constructs an empty IOTA DID Document with a [placeholder](#IotaDID.placeholder) identifier +for the given `network`. + +| Param | Type | +| ------- | ------------------- | +| network | string | + + + +### iotaDocument.id() ⇒ [IotaDID](#IotaDID) + +Returns a copy of the DID Document `id`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.controller() ⇒ [Array.<IotaDID>](#IotaDID) + +Returns a copy of the list of document controllers. + +NOTE: controllers are determined by the `state_controller` unlock condition of the output +during resolution and are omitted when publishing. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.alsoKnownAs() ⇒ Array.<string> + +Returns a copy of the document's `alsoKnownAs` set. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.setAlsoKnownAs(urls) + +Sets the `alsoKnownAs` property in the DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ----------------------------------------------------------------------------- | +| urls | string \| Array.<string> \| null | + + + +### iotaDocument.properties() ⇒ Map.<string, any> + +Returns a copy of the custom DID Document properties. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.setPropertyUnchecked(key, value) + +Sets a custom property in the DID Document. +If the value is set to `null`, the custom property will be removed. + +### WARNING + +This method can overwrite existing properties like `id` and result in an invalid document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ------------------- | +| key | string | +| value | any | + + + +### iotaDocument.service() ⇒ [Array.<Service>](#Service) + +Return a set of all [Service](#Service) in the document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.insertService(service) + +Add a new [Service](#Service) to the document. + +Returns `true` if the service was added. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------- | -------------------------------- | +| service | [Service](#Service) | + + + +### iotaDocument.removeService(did) ⇒ [Service](#Service) \| undefined + +Remove a [Service](#Service) identified by the given [DIDUrl](#DIDUrl) from the document. + +Returns `true` if a service was removed. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ------------------------------ | +| did | [DIDUrl](#DIDUrl) | + + + +### iotaDocument.resolveService(query) ⇒ [Service](#Service) \| undefined + +Returns the first [Service](#Service) with an `id` property matching the provided `query`, +if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ----------------------------------------------------- | +| query | [DIDUrl](#DIDUrl) \| string | + + + +### iotaDocument.methods(scope) ⇒ [Array.<VerificationMethod>](#VerificationMethod) + +Returns a list of all [VerificationMethod](#VerificationMethod) in the DID Document, +whose verification relationship matches `scope`. + +If `scope` is not set, a list over the **embedded** methods is returned. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ------------------------------------------------------------------ | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### iotaDocument.insertMethod(method, scope) + +Adds a new `method` to the document in the given `scope`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------ | ------------------------------------------------------ | +| method | [VerificationMethod](#VerificationMethod) | +| scope | [MethodScope](#MethodScope) | + + + +### iotaDocument.removeMethod(did) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + +Removes all references to the specified Verification Method. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ------------------------------ | +| did | [DIDUrl](#DIDUrl) | + + + +### iotaDocument.resolveMethod(query, scope) ⇒ [VerificationMethod](#VerificationMethod) \| undefined + +Returns a copy of the first verification method with an `id` property +matching the provided `query` and the verification relationship +specified by `scope`, if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ------------------------------------------------------------------ | +| query | [DIDUrl](#DIDUrl) \| string | +| scope | [MethodScope](#MethodScope) \| undefined | + + + +### iotaDocument.attachMethodRelationship(didUrl, relationship) ⇒ boolean + +Attaches the relationship to the given method, if the method exists. + +Note: The method needs to be in the set of verification methods, +so it cannot be an embedded one. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------------ | ------------------------------ | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### iotaDocument.detachMethodRelationship(didUrl, relationship) ⇒ boolean + +Detaches the given relationship from the given method, if the method exists. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------------ | ------------------------------ | +| didUrl | [DIDUrl](#DIDUrl) | +| relationship | number | + + + +### iotaDocument.verifyJws(jws, options, signatureVerifier, detachedPayload) ⇒ [DecodedJws](#DecodedJws) + +Decodes and verifies the provided JWS according to the passed `options` and `signatureVerifier`. +If no `signatureVerifier` argument is provided a default verifier will be used that is (only) capable of +verifying EdDSA signatures. + +Regardless of which options are passed the following conditions must be met in order for a verification attempt to +take place. + +- The JWS must be encoded according to the JWS compact serialization. +- The `kid` value in the protected header must be an identifier of a verification method in this DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----------------- | -------------------------------------------------------------- | +| jws | [Jws](#Jws) | +| options | [JwsVerificationOptions](#JwsVerificationOptions) | +| signatureVerifier | IJwsVerifier | +| detachedPayload | string \| undefined | + + + +### iotaDocument.pack() ⇒ Uint8Array + +Serializes the document for inclusion in an Alias Output's state metadata +with the default [StateMetadataEncoding](#StateMetadataEncoding). + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.packWithEncoding(encoding) ⇒ Uint8Array + +Serializes the document for inclusion in an Alias Output's state metadata. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| -------- | ------------------- | +| encoding | number | + + + +### iotaDocument.metadata() ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + +Returns a copy of the metadata associated with this document. + +NOTE: Copies all the metadata. See also `metadataCreated`, `metadataUpdated`, +`metadataPreviousMessageId`, `metadataProof` if only a subset of the metadata required. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.metadataCreated() ⇒ [Timestamp](#Timestamp) \| undefined + +Returns a copy of the timestamp of when the DID document was created. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.setMetadataCreated(timestamp) + +Sets the timestamp of when the DID document was created. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --------- | -------------------------------------------------------------- | +| timestamp | [Timestamp](#Timestamp) \| undefined | + + + +### iotaDocument.metadataUpdated() ⇒ [Timestamp](#Timestamp) \| undefined + +Returns a copy of the timestamp of the last DID document update. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.setMetadataUpdated(timestamp) + +Sets the timestamp of the last DID document update. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| --------- | -------------------------------------------------------------- | +| timestamp | [Timestamp](#Timestamp) \| undefined | + + + +### iotaDocument.metadataDeactivated() ⇒ boolean \| undefined + +Returns a copy of the deactivated status of the DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.setMetadataDeactivated(deactivated) + +Sets the deactivated status of the DID document. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----------- | ---------------------------------------------- | +| deactivated | boolean \| undefined | + + + +### iotaDocument.metadataStateControllerAddress() ⇒ string \| undefined + +Returns a copy of the Bech32-encoded state controller address, if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.metadataGovernorAddress() ⇒ string \| undefined + +Returns a copy of the Bech32-encoded governor address, if present. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.setMetadataPropertyUnchecked(key, value) + +Sets a custom property in the document metadata. +If the value is set to `null`, the custom property will be removed. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ------------------- | +| key | string | +| value | any | + + + +### iotaDocument.revokeCredentials(serviceQuery, indices) + +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +revoke all specified `indices`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------------ | -------------------------------------------------------- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### iotaDocument.unrevokeCredentials(serviceQuery, indices) + +If the document has a [RevocationBitmap](#RevocationBitmap) service identified by `serviceQuery`, +unrevoke all specified `indices`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------------ | -------------------------------------------------------- | +| serviceQuery | [DIDUrl](#DIDUrl) \| string | +| indices | number \| Array.<number> | + + + +### iotaDocument.clone() ⇒ [IotaDocument](#IotaDocument) + +Returns a deep clone of the [IotaDocument](#IotaDocument). + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.\_shallowCloneInternal() ⇒ [IotaDocument](#IotaDocument) + +### Warning + +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.\_strongCountInternal() ⇒ number + +### Warning + +This is for internal use only. Do not rely on or call this method. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.toJSON() ⇒ any + +Serializes to a plain JS representation. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.toCoreDocument() ⇒ [CoreDocument](#CoreDocument) + +Transforms the [IotaDocument](#IotaDocument) to its [CoreDocument](#CoreDocument) representation. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + + + +### iotaDocument.generateMethod(storage, keyType, alg, fragment, scope) ⇒ Promise.<string> + +Generate new key material in the given `storage` and insert a new verification method with the corresponding +public key material into the DID document. + +- If no fragment is given the `kid` of the generated JWK is used, if it is set, otherwise an error is returned. +- The `keyType` must be compatible with the given `storage`. `Storage`s are expected to export key type constants + for that use case. + +The fragment of the generated method is returned. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| -------- | --------------------------------------------- | +| storage | [Storage](#Storage) | +| keyType | string | +| alg | JwsAlgorithm | +| fragment | string \| undefined | +| scope | [MethodScope](#MethodScope) | + + + +### iotaDocument.purgeMethod(storage, id) ⇒ Promise.<void> + +Remove the method identified by the given fragment from the document and delete the corresponding key material in +the given `storage`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------- | -------------------------------- | +| storage | [Storage](#Storage) | +| id | [DIDUrl](#DIDUrl) | + + + +### iotaDocument.createJwt(storage, fragment, payload, options) ⇒ [Promise.<Jws>](#Jws) + +Sign the `payload` according to `options` with the storage backed private key corresponding to the public key +material in the verification method identified by the given `fragment. + +Upon success a string representing a JWS encoded according to the Compact JWS Serialization format is returned. +See [RFC7515 section 3.1](https://www.rfc-editor.org/rfc/rfc7515#section-3.1). + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| -------- | -------------------------------------------------------- | +| storage | [Storage](#Storage) | +| fragment | string | +| payload | string | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | + + + +### iotaDocument.createCredentialJwt(storage, fragment, credential, options, custom_claims) ⇒ [Promise.<Jwt>](#Jwt) + +Produces a JWS where the payload is produced from the given `credential` +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +The `custom_claims` can be used to set additional claims on the resulting JWT. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------------- | ----------------------------------------------------------------- | +| storage | [Storage](#Storage) | +| fragment | string | +| credential | [Credential](#Credential) | +| options | [JwsSignatureOptions](#JwsSignatureOptions) | +| custom_claims | Record.<string, any> \| undefined | + + + +### iotaDocument.createPresentationJwt(storage, fragment, presentation, signature_options, presentation_options) ⇒ [Promise.<Jwt>](#Jwt) + +Produces a JWT where the payload is produced from the given presentation. +in accordance with [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token). + +Unless the `kid` is explicitly set in the options, the `kid` in the protected header is the `id` +of the method identified by `fragment` and the JWS signature will be produced by the corresponding +private key backed by the `storage` in accordance with the passed `options`. + +**Kind**: instance method of [IotaDocument](#IotaDocument) + +| Param | Type | +| -------------------- | -------------------------------------------------------------- | +| storage | [Storage](#Storage) | +| fragment | string | +| presentation | [Presentation](#Presentation) | +| signature_options | [JwsSignatureOptions](#JwsSignatureOptions) | +| presentation_options | [JwtPresentationOptions](#JwtPresentationOptions) | + + + +### IotaDocument.newWithId(id) ⇒ [IotaDocument](#IotaDocument) + +Constructs an empty DID Document with the given identifier. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | -------------------------------- | +| id | [IotaDID](#IotaDID) | + + + +### IotaDocument.unpackFromOutput(did, aliasOutput, allowEmpty) ⇒ [IotaDocument](#IotaDocument) + +Deserializes the document from an Alias Output. + +If `allowEmpty` is true, this will return an empty DID document marked as `deactivated` +if `stateMetadata` is empty. + +The `tokenSupply` must be equal to the token supply of the network the DID is associated with. + +NOTE: `did` is required since it is omitted from the serialized DID Document and +cannot be inferred from the state metadata. It also indicates the network, which is not +encoded in the `AliasId` alone. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----------- | ------------------------------------- | +| did | [IotaDID](#IotaDID) | +| aliasOutput | AliasOutputBuilderParams | +| allowEmpty | boolean | + + + +### IotaDocument.unpackFromBlock(network, block) ⇒ [Array.<IotaDocument>](#IotaDocument) + +Returns all DID documents of the Alias Outputs contained in the block's transaction payload +outputs, if any. + +Errors if any Alias Output does not contain a valid or empty DID Document. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ------- | ------------------- | +| network | string | +| block | Block | + + + +### IotaDocument.fromJSON(json) ⇒ [IotaDocument](#IotaDocument) + +Deserializes an instance from a plain JS representation. + +**Kind**: static method of [IotaDocument](#IotaDocument) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## IotaDocumentMetadata + +Additional attributes related to an IOTA DID Document. + +**Kind**: global class + +- [IotaDocumentMetadata](#IotaDocumentMetadata) + - _instance_ + - [.created()](#IotaDocumentMetadata+created) ⇒ [Timestamp](#Timestamp) \| undefined + - [.updated()](#IotaDocumentMetadata+updated) ⇒ [Timestamp](#Timestamp) \| undefined + - [.deactivated()](#IotaDocumentMetadata+deactivated) ⇒ boolean \| undefined + - [.stateControllerAddress()](#IotaDocumentMetadata+stateControllerAddress) ⇒ string \| undefined + - [.governorAddress()](#IotaDocumentMetadata+governorAddress) ⇒ string \| undefined + - [.properties()](#IotaDocumentMetadata+properties) ⇒ Map.<string, any> + - [.toJSON()](#IotaDocumentMetadata+toJSON) ⇒ any + - [.clone()](#IotaDocumentMetadata+clone) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + - _static_ + - [.fromJSON(json)](#IotaDocumentMetadata.fromJSON) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.created() ⇒ [Timestamp](#Timestamp) \| undefined + +Returns a copy of the timestamp of when the DID document was created. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.updated() ⇒ [Timestamp](#Timestamp) \| undefined + +Returns a copy of the timestamp of the last DID document update. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.deactivated() ⇒ boolean \| undefined + +Returns a copy of the deactivated status of the DID document. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.stateControllerAddress() ⇒ string \| undefined + +Returns a copy of the Bech32-encoded state controller address, if present. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.governorAddress() ⇒ string \| undefined + +Returns a copy of the Bech32-encoded governor address, if present. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.properties() ⇒ Map.<string, any> + +Returns a copy of the custom metadata properties. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### iotaDocumentMetadata.clone() ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + +Deep clones the object. + +**Kind**: instance method of [IotaDocumentMetadata](#IotaDocumentMetadata) + + + +### IotaDocumentMetadata.fromJSON(json) ⇒ [IotaDocumentMetadata](#IotaDocumentMetadata) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [IotaDocumentMetadata](#IotaDocumentMetadata) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## IotaIdentityClientExt + +An extension interface that provides helper functions for publication +and resolution of DID documents in Alias Outputs. + +**Kind**: global class + +- [IotaIdentityClientExt](#IotaIdentityClientExt) + - [.newDidOutput(client, address, document, rentStructure)](#IotaIdentityClientExt.newDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + - [.updateDidOutput(client, document)](#IotaIdentityClientExt.updateDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + - [.deactivateDidOutput(client, did)](#IotaIdentityClientExt.deactivateDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + - [.resolveDid(client, did)](#IotaIdentityClientExt.resolveDid) ⇒ [Promise.<IotaDocument>](#IotaDocument) + - [.resolveDidOutput(client, did)](#IotaIdentityClientExt.resolveDidOutput) ⇒ Promise.<AliasOutputBuilderParams> + + + +### IotaIdentityClientExt.newDidOutput(client, address, document, rentStructure) ⇒ Promise.<AliasOutputBuilderParams> + +Create a DID with a new Alias Output containing the given `document`. + +The `address` will be set as the state controller and governor unlock conditions. +The minimum required token deposit amount will be set according to the given +`rent_structure`, which will be fetched from the node if not provided. +The returned Alias Output can be further customised before publication, if desired. + +NOTE: this does _not_ publish the Alias Output. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| ------------- | -------------------------------------------- | +| client | IIotaIdentityClient | +| address | Address | +| document | [IotaDocument](#IotaDocument) | +| rentStructure | IRent \| undefined | + + + +### IotaIdentityClientExt.updateDidOutput(client, document) ⇒ Promise.<AliasOutputBuilderParams> + +Fetches the associated Alias Output and updates it with `document` in its state metadata. +The storage deposit on the output is left unchanged. If the size of the document increased, +the amount should be increased manually. + +NOTE: this does _not_ publish the updated Alias Output. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| -------- | ------------------------------------------ | +| client | IIotaIdentityClient | +| document | [IotaDocument](#IotaDocument) | + + + +### IotaIdentityClientExt.deactivateDidOutput(client, did) ⇒ Promise.<AliasOutputBuilderParams> + +Removes the DID document from the state metadata of its Alias Output, +effectively deactivating it. The storage deposit on the output is left unchanged, +and should be reallocated manually. + +Deactivating does not destroy the output. Hence, it can be re-activated by publishing +an update containing a DID document. + +NOTE: this does _not_ publish the updated Alias Output. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| ------ | -------------------------------- | +| client | IIotaIdentityClient | +| did | [IotaDID](#IotaDID) | + + + +### IotaIdentityClientExt.resolveDid(client, did) ⇒ [Promise.<IotaDocument>](#IotaDocument) + +Resolve a [IotaDocument](#IotaDocument). Returns an empty, deactivated document if the state metadata +of the Alias Output is empty. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| ------ | -------------------------------- | +| client | IIotaIdentityClient | +| did | [IotaDID](#IotaDID) | + + + +### IotaIdentityClientExt.resolveDidOutput(client, did) ⇒ Promise.<AliasOutputBuilderParams> + +Fetches the `IAliasOutput` associated with the given DID. + +**Kind**: static method of [IotaIdentityClientExt](#IotaIdentityClientExt) + +| Param | Type | +| ------ | -------------------------------- | +| client | IIotaIdentityClient | +| did | [IotaDID](#IotaDID) | + + + +## Jwk + +**Kind**: global class + +- [Jwk](#Jwk) + - [new Jwk(jwk)](#new_Jwk_new) + - _instance_ + - [.kty()](#Jwk+kty) ⇒ JwkType + - [.use()](#Jwk+use) ⇒ JwkUse \| undefined + - [.keyOps()](#Jwk+keyOps) ⇒ Array.<JwkOperation> + - [.alg()](#Jwk+alg) ⇒ JwsAlgorithm \| undefined + - [.kid()](#Jwk+kid) ⇒ string \| undefined + - [.x5u()](#Jwk+x5u) ⇒ string \| undefined + - [.x5c()](#Jwk+x5c) ⇒ Array.<string> + - [.x5t()](#Jwk+x5t) ⇒ string \| undefined + - [.x5t256()](#Jwk+x5t256) ⇒ string \| undefined + - [.paramsEc()](#Jwk+paramsEc) ⇒ JwkParamsEc \| undefined + - [.paramsOkp()](#Jwk+paramsOkp) ⇒ JwkParamsOkp \| undefined + - [.paramsOct()](#Jwk+paramsOct) ⇒ JwkParamsOct \| undefined + - [.paramsRsa()](#Jwk+paramsRsa) ⇒ JwkParamsRsa \| undefined + - [.toPublic()](#Jwk+toPublic) ⇒ [Jwk](#Jwk) \| undefined + - [.isPublic()](#Jwk+isPublic) ⇒ boolean + - [.isPrivate()](#Jwk+isPrivate) ⇒ boolean + - [.toJSON()](#Jwk+toJSON) ⇒ any + - [.clone()](#Jwk+clone) ⇒ [Jwk](#Jwk) + - _static_ + - [.fromJSON(json)](#Jwk.fromJSON) ⇒ [Jwk](#Jwk) + + + +### new Jwk(jwk) + +| Param | Type | +| ----- | ----------------------- | +| jwk | IJwkParams | + + + +### jwk.kty() ⇒ JwkType + +Returns the value for the key type parameter (kty). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.use() ⇒ JwkUse \| undefined + +Returns the value for the use property (use). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.keyOps() ⇒ Array.<JwkOperation> + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.alg() ⇒ JwsAlgorithm \| undefined + +Returns the value for the algorithm property (alg). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.kid() ⇒ string \| undefined + +Returns the value of the key ID property (kid). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.x5u() ⇒ string \| undefined + +Returns the value of the X.509 URL property (x5u). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.x5c() ⇒ Array.<string> + +Returns the value of the X.509 certificate chain property (x5c). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.x5t() ⇒ string \| undefined + +Returns the value of the X.509 certificate SHA-1 thumbprint property (x5t). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.x5t256() ⇒ string \| undefined + +Returns the value of the X.509 certificate SHA-256 thumbprint property (x5t#S256). + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.paramsEc() ⇒ JwkParamsEc \| undefined + +If this JWK is of kty EC, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.paramsOkp() ⇒ JwkParamsOkp \| undefined + +If this JWK is of kty OKP, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.paramsOct() ⇒ JwkParamsOct \| undefined + +If this JWK is of kty OCT, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.paramsRsa() ⇒ JwkParamsRsa \| undefined + +If this JWK is of kty RSA, returns those parameters. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.toPublic() ⇒ [Jwk](#Jwk) \| undefined + +Returns a clone of the [Jwk](#Jwk) with _all_ private key components unset. +Nothing is returned when `kty = oct` as this key type is not considered public by this library. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.isPublic() ⇒ boolean + +Returns `true` if _all_ private key components of the key are unset, `false` otherwise. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.isPrivate() ⇒ boolean + +Returns `true` if _all_ private key components of the key are set, `false` otherwise. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### jwk.clone() ⇒ [Jwk](#Jwk) + +Deep clones the object. + +**Kind**: instance method of [Jwk](#Jwk) + + + +### Jwk.fromJSON(json) ⇒ [Jwk](#Jwk) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Jwk](#Jwk) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## JwkGenOutput + +The result of a key generation in `JwkStorage`. + +**Kind**: global class + +- [JwkGenOutput](#JwkGenOutput) + - [new JwkGenOutput(key_id, jwk)](#new_JwkGenOutput_new) + - _instance_ + - [.jwk()](#JwkGenOutput+jwk) ⇒ [Jwk](#Jwk) + - [.keyId()](#JwkGenOutput+keyId) ⇒ string + - [.toJSON()](#JwkGenOutput+toJSON) ⇒ any + - [.clone()](#JwkGenOutput+clone) ⇒ [JwkGenOutput](#JwkGenOutput) + - _static_ + - [.fromJSON(json)](#JwkGenOutput.fromJSON) ⇒ [JwkGenOutput](#JwkGenOutput) + + + +### new JwkGenOutput(key_id, jwk) + +| Param | Type | +| ------ | ------------------------ | +| key_id | string | +| jwk | [Jwk](#Jwk) | + + + +### jwkGenOutput.jwk() ⇒ [Jwk](#Jwk) + +Returns the generated public [Jwk](#Jwk). + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + + +### jwkGenOutput.keyId() ⇒ string + +Returns the key id of the generated [Jwk](#Jwk). + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + + +### jwkGenOutput.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + + +### jwkGenOutput.clone() ⇒ [JwkGenOutput](#JwkGenOutput) + +Deep clones the object. + +**Kind**: instance method of [JwkGenOutput](#JwkGenOutput) + + + +### JwkGenOutput.fromJSON(json) ⇒ [JwkGenOutput](#JwkGenOutput) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwkGenOutput](#JwkGenOutput) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## Jws + +A wrapper around a JSON Web Signature (JWS). + +**Kind**: global class + +- [Jws](#Jws) + - [new Jws(jws_string)](#new_Jws_new) + - [.toString()](#Jws+toString) ⇒ string + + + +### new Jws(jws_string) + +Creates a new [Jws](#Jws) from the given string. + +| Param | Type | +| ---------- | ------------------- | +| jws_string | string | + + + +### jws.toString() ⇒ string + +Returns a clone of the JWS string. + +**Kind**: instance method of [Jws](#Jws) + + + +## JwsHeader + +**Kind**: global class + +- [JwsHeader](#JwsHeader) + - [new JwsHeader()](#new_JwsHeader_new) + - _instance_ + - [.alg()](#JwsHeader+alg) ⇒ JwsAlgorithm \| undefined + - [.setAlg(value)](#JwsHeader+setAlg) + - [.b64()](#JwsHeader+b64) ⇒ boolean \| undefined + - [.setB64(value)](#JwsHeader+setB64) + - [.custom()](#JwsHeader+custom) ⇒ Record.<string, any> \| undefined + - [.has(claim)](#JwsHeader+has) ⇒ boolean + - [.isDisjoint(other)](#JwsHeader+isDisjoint) ⇒ boolean + - [.jku()](#JwsHeader+jku) ⇒ string \| undefined + - [.setJku(value)](#JwsHeader+setJku) + - [.jwk()](#JwsHeader+jwk) ⇒ [Jwk](#Jwk) \| undefined + - [.setJwk(value)](#JwsHeader+setJwk) + - [.kid()](#JwsHeader+kid) ⇒ string \| undefined + - [.setKid(value)](#JwsHeader+setKid) + - [.x5u()](#JwsHeader+x5u) ⇒ string \| undefined + - [.setX5u(value)](#JwsHeader+setX5u) + - [.x5c()](#JwsHeader+x5c) ⇒ Array.<string> + - [.setX5c(value)](#JwsHeader+setX5c) + - [.x5t()](#JwsHeader+x5t) ⇒ string \| undefined + - [.setX5t(value)](#JwsHeader+setX5t) + - [.x5tS256()](#JwsHeader+x5tS256) ⇒ string \| undefined + - [.setX5tS256(value)](#JwsHeader+setX5tS256) + - [.typ()](#JwsHeader+typ) ⇒ string \| undefined + - [.setTyp(value)](#JwsHeader+setTyp) + - [.cty()](#JwsHeader+cty) ⇒ string \| undefined + - [.setCty(value)](#JwsHeader+setCty) + - [.crit()](#JwsHeader+crit) ⇒ Array.<string> + - [.setCrit(value)](#JwsHeader+setCrit) + - [.url()](#JwsHeader+url) ⇒ string \| undefined + - [.setUrl(value)](#JwsHeader+setUrl) + - [.nonce()](#JwsHeader+nonce) ⇒ string \| undefined + - [.setNonce(value)](#JwsHeader+setNonce) + - [.toJSON()](#JwsHeader+toJSON) ⇒ any + - [.clone()](#JwsHeader+clone) ⇒ [JwsHeader](#JwsHeader) + - _static_ + - [.fromJSON(json)](#JwsHeader.fromJSON) ⇒ [JwsHeader](#JwsHeader) + + + +### new JwsHeader() + +Create a new empty [JwsHeader](#JwsHeader). + + + +### jwsHeader.alg() ⇒ JwsAlgorithm \| undefined + +Returns the value for the algorithm claim (alg). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setAlg(value) + +Sets a value for the algorithm claim (alg). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------------- | +| value | JwsAlgorithm | + + + +### jwsHeader.b64() ⇒ boolean \| undefined + +Returns the value of the base64url-encode payload claim (b64). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setB64(value) + +Sets a value for the base64url-encode payload claim (b64). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | -------------------- | +| value | boolean | + + + +### jwsHeader.custom() ⇒ Record.<string, any> \| undefined + +Additional header parameters. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.has(claim) ⇒ boolean + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| claim | string | + + + +### jwsHeader.isDisjoint(other) ⇒ boolean + +Returns `true` if none of the fields are set in both `self` and `other`. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------------------------ | +| other | [JwsHeader](#JwsHeader) | + + + +### jwsHeader.jku() ⇒ string \| undefined + +Returns the value of the JWK Set URL claim (jku). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setJku(value) + +Sets a value for the JWK Set URL claim (jku). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.jwk() ⇒ [Jwk](#Jwk) \| undefined + +Returns the value of the JWK claim (jwk). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setJwk(value) + +Sets a value for the JWK claim (jwk). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------------ | +| value | [Jwk](#Jwk) | + + + +### jwsHeader.kid() ⇒ string \| undefined + +Returns the value of the key ID claim (kid). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setKid(value) + +Sets a value for the key ID claim (kid). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.x5u() ⇒ string \| undefined + +Returns the value of the X.509 URL claim (x5u). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setX5u(value) + +Sets a value for the X.509 URL claim (x5u). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.x5c() ⇒ Array.<string> + +Returns the value of the X.509 certificate chain claim (x5c). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setX5c(value) + +Sets values for the X.509 certificate chain claim (x5c). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | --------------------------------- | +| value | Array.<string> | + + + +### jwsHeader.x5t() ⇒ string \| undefined + +Returns the value of the X.509 certificate SHA-1 thumbprint claim (x5t). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setX5t(value) + +Sets a value for the X.509 certificate SHA-1 thumbprint claim (x5t). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.x5tS256() ⇒ string \| undefined + +Returns the value of the X.509 certificate SHA-256 thumbprint claim +(x5t#S256). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setX5tS256(value) + +Sets a value for the X.509 certificate SHA-256 thumbprint claim +(x5t#S256). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.typ() ⇒ string \| undefined + +Returns the value of the token type claim (typ). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setTyp(value) + +Sets a value for the token type claim (typ). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.cty() ⇒ string \| undefined + +Returns the value of the content type claim (cty). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setCty(value) + +Sets a value for the content type claim (cty). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.crit() ⇒ Array.<string> + +Returns the value of the critical claim (crit). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setCrit(value) + +Sets values for the critical claim (crit). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | --------------------------------- | +| value | Array.<string> | + + + +### jwsHeader.url() ⇒ string \| undefined + +Returns the value of the url claim (url). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setUrl(value) + +Sets a value for the url claim (url). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.nonce() ⇒ string \| undefined + +Returns the value of the nonce claim (nonce). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.setNonce(value) + +Sets a value for the nonce claim (nonce). + +**Kind**: instance method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsHeader.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### jwsHeader.clone() ⇒ [JwsHeader](#JwsHeader) + +Deep clones the object. + +**Kind**: instance method of [JwsHeader](#JwsHeader) + + + +### JwsHeader.fromJSON(json) ⇒ [JwsHeader](#JwsHeader) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwsHeader](#JwsHeader) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## JwsSignatureOptions + +**Kind**: global class + +- [JwsSignatureOptions](#JwsSignatureOptions) + - [new JwsSignatureOptions(options)](#new_JwsSignatureOptions_new) + - _instance_ + - [.setAttachJwk(value)](#JwsSignatureOptions+setAttachJwk) + - [.setB64(value)](#JwsSignatureOptions+setB64) + - [.setTyp(value)](#JwsSignatureOptions+setTyp) + - [.setCty(value)](#JwsSignatureOptions+setCty) + - [.serUrl(value)](#JwsSignatureOptions+serUrl) + - [.setNonce(value)](#JwsSignatureOptions+setNonce) + - [.setKid(value)](#JwsSignatureOptions+setKid) + - [.setDetachedPayload(value)](#JwsSignatureOptions+setDetachedPayload) + - [.setCustomHeaderParameters(value)](#JwsSignatureOptions+setCustomHeaderParameters) + - [.toJSON()](#JwsSignatureOptions+toJSON) ⇒ any + - [.clone()](#JwsSignatureOptions+clone) ⇒ [JwsSignatureOptions](#JwsSignatureOptions) + - _static_ + - [.fromJSON(json)](#JwsSignatureOptions.fromJSON) ⇒ [JwsSignatureOptions](#JwsSignatureOptions) + + + +### new JwsSignatureOptions(options) + +| Param | Type | +| ------- | ----------------------------------------------------------- | +| options | IJwsSignatureOptions \| undefined | + + + +### jwsSignatureOptions.setAttachJwk(value) + +Replace the value of the `attachJwk` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | -------------------- | +| value | boolean | + + + +### jwsSignatureOptions.setB64(value) + +Replace the value of the `b64` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | -------------------- | +| value | boolean | + + + +### jwsSignatureOptions.setTyp(value) + +Replace the value of the `typ` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsSignatureOptions.setCty(value) + +Replace the value of the `cty` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsSignatureOptions.serUrl(value) + +Replace the value of the `url` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsSignatureOptions.setNonce(value) + +Replace the value of the `nonce` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsSignatureOptions.setKid(value) + +Replace the value of the `kid` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsSignatureOptions.setDetachedPayload(value) + +Replace the value of the `detached_payload` field. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | -------------------- | +| value | boolean | + + + +### jwsSignatureOptions.setCustomHeaderParameters(value) + +Add additional header parameters. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | --------------------------------------- | +| value | Record.<string, any> | + + + +### jwsSignatureOptions.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + + + +### jwsSignatureOptions.clone() ⇒ [JwsSignatureOptions](#JwsSignatureOptions) + +Deep clones the object. + +**Kind**: instance method of [JwsSignatureOptions](#JwsSignatureOptions) + + + +### JwsSignatureOptions.fromJSON(json) ⇒ [JwsSignatureOptions](#JwsSignatureOptions) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwsSignatureOptions](#JwsSignatureOptions) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## JwsVerificationOptions + +**Kind**: global class + +- [JwsVerificationOptions](#JwsVerificationOptions) + - [new JwsVerificationOptions(options)](#new_JwsVerificationOptions_new) + - _instance_ + - [.setNonce(value)](#JwsVerificationOptions+setNonce) + - [.setMethodScope(value)](#JwsVerificationOptions+setMethodScope) + - [.setMethodId(value)](#JwsVerificationOptions+setMethodId) + - [.toJSON()](#JwsVerificationOptions+toJSON) ⇒ any + - [.clone()](#JwsVerificationOptions+clone) ⇒ [JwsVerificationOptions](#JwsVerificationOptions) + - _static_ + - [.fromJSON(json)](#JwsVerificationOptions.fromJSON) ⇒ [JwsVerificationOptions](#JwsVerificationOptions) + + + +### new JwsVerificationOptions(options) + +Creates a new [JwsVerificationOptions](#JwsVerificationOptions) from the given fields. + +| Param | Type | +| ------- | -------------------------------------------------------------- | +| options | IJwsVerificationOptions \| undefined | + + + +### jwsVerificationOptions.setNonce(value) + +Set the expected value for the `nonce` parameter of the protected header. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| ----- | ------------------- | +| value | string | + + + +### jwsVerificationOptions.setMethodScope(value) + +Set the scope of the verification methods that may be used to verify the given JWS. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| ----- | ---------------------------------------- | +| value | [MethodScope](#MethodScope) | + + + +### jwsVerificationOptions.setMethodId(value) + +Set the DID URl of the method, whose JWK should be used to verify the JWS. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| ----- | ------------------------------ | +| value | [DIDUrl](#DIDUrl) | + + + +### jwsVerificationOptions.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + + + +### jwsVerificationOptions.clone() ⇒ [JwsVerificationOptions](#JwsVerificationOptions) + +Deep clones the object. + +**Kind**: instance method of [JwsVerificationOptions](#JwsVerificationOptions) + + + +### JwsVerificationOptions.fromJSON(json) ⇒ [JwsVerificationOptions](#JwsVerificationOptions) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwsVerificationOptions](#JwsVerificationOptions) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## Jwt + +A wrapper around a JSON Web Token (JWK). + +**Kind**: global class + +- [Jwt](#Jwt) + - [new Jwt(jwt_string)](#new_Jwt_new) + - _instance_ + - [.toString()](#Jwt+toString) ⇒ string + - [.toJSON()](#Jwt+toJSON) ⇒ any + - [.clone()](#Jwt+clone) ⇒ [Jwt](#Jwt) + - _static_ + - [.fromJSON(json)](#Jwt.fromJSON) ⇒ [Jwt](#Jwt) + + + +### new Jwt(jwt_string) + +Creates a new [Jwt](#Jwt) from the given string. + +| Param | Type | +| ---------- | ------------------- | +| jwt_string | string | + + + +### jwt.toString() ⇒ string + +Returns a clone of the JWT string. + +**Kind**: instance method of [Jwt](#Jwt) + + + +### jwt.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Jwt](#Jwt) + + + +### jwt.clone() ⇒ [Jwt](#Jwt) + +Deep clones the object. + +**Kind**: instance method of [Jwt](#Jwt) + + + +### Jwt.fromJSON(json) ⇒ [Jwt](#Jwt) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Jwt](#Jwt) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## JwtCredentialValidationOptions + +Options to declare validation criteria when validating credentials. + +**Kind**: global class + +- [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + - [new JwtCredentialValidationOptions(options)](#new_JwtCredentialValidationOptions_new) + - _instance_ + - [.toJSON()](#JwtCredentialValidationOptions+toJSON) ⇒ any + - [.clone()](#JwtCredentialValidationOptions+clone) ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + - _static_ + - [.fromJSON(json)](#JwtCredentialValidationOptions.fromJSON) ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + + + +### new JwtCredentialValidationOptions(options) + +| Param | Type | +| ------- | ---------------------------------------------------------------------- | +| options | IJwtCredentialValidationOptions \| undefined | + + + +### jwtCredentialValidationOptions.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + + + +### jwtCredentialValidationOptions.clone() ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + +Deep clones the object. + +**Kind**: instance method of [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + + + +### JwtCredentialValidationOptions.fromJSON(json) ⇒ [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## JwtCredentialValidator + +A type for decoding and validating [Credential](#Credential). + +**Kind**: global class + +- [JwtCredentialValidator](#JwtCredentialValidator) + - [new JwtCredentialValidator(signatureVerifier)](#new_JwtCredentialValidator_new) + - _instance_ + - [.validate(credential_jwt, issuer, options, fail_fast)](#JwtCredentialValidator+validate) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + - [.verifySignature(credential, trustedIssuers, options)](#JwtCredentialValidator+verifySignature) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + - _static_ + - [.checkExpiresOnOrAfter(credential, timestamp)](#JwtCredentialValidator.checkExpiresOnOrAfter) + - [.checkIssuedOnOrBefore(credential, timestamp)](#JwtCredentialValidator.checkIssuedOnOrBefore) + - [.checkSubjectHolderRelationship(credential, holder, relationship)](#JwtCredentialValidator.checkSubjectHolderRelationship) + - [.checkStatus(credential, trustedIssuers, statusCheck)](#JwtCredentialValidator.checkStatus) + - [.extractIssuer(credential)](#JwtCredentialValidator.extractIssuer) ⇒ [CoreDID](#CoreDID) + - [.extractIssuerFromJwt(credential)](#JwtCredentialValidator.extractIssuerFromJwt) ⇒ [CoreDID](#CoreDID) + + + +### new JwtCredentialValidator(signatureVerifier) + +Creates a new [JwtCredentialValidator](#JwtCredentialValidator). If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + +| Param | Type | +| ----------------- | ------------------------- | +| signatureVerifier | IJwsVerifier | + + + +### jwtCredentialValidator.validate(credential_jwt, issuer, options, fail_fast) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + +Decodes and validates a [Credential](#Credential) issued as a JWS. A [DecodedJwtCredential](#DecodedJwtCredential) is returned upon +success. + +The following properties are validated according to `options`: + +- the issuer's signature on the JWS, +- the expiration date, +- the issuance date, +- the semantic structure. + +# Warning + +The lack of an error returned from this method is in of itself not enough to conclude that the credential can be +trusted. This section contains more information on additional checks that should be carried out before and after +calling this method. + +## The state of the issuer's DID Document + +The caller must ensure that `issuer` represents an up-to-date DID Document. + +## Properties that are not validated + +There are many properties defined in [The Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) that are **not** validated, such as: +`proof`, `credentialStatus`, `type`, `credentialSchema`, `refreshService` **and more**. +These should be manually checked after validation, according to your requirements. + +# Errors + +An error is returned whenever a validated condition is not satisfied. + +**Kind**: instance method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| -------------- | ------------------------------------------------------------------------------ | +| credential_jwt | [Jwt](#Jwt) | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | +| fail_fast | number | + + + +### jwtCredentialValidator.verifySignature(credential, trustedIssuers, options) ⇒ [DecodedJwtCredential](#DecodedJwtCredential) + +Decode and verify the JWS signature of a [Credential](#Credential) issued as a JWT using the DID Document of a trusted +issuer. + +A [DecodedJwtCredential](#DecodedJwtCredential) is returned upon success. + +# Warning + +The caller must ensure that the DID Documents of the trusted issuers are up-to-date. + +## Proofs + +Only the JWS signature is verified. If the [Credential](#Credential) contains a `proof` property this will not be +verified by this method. + +# Errors + +This method immediately returns an error if +the credential issuer' url cannot be parsed to a DID belonging to one of the trusted issuers. Otherwise an attempt +to verify the credential's signature will be made and an error is returned upon failure. + +**Kind**: instance method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| -------------- | -------------------------------------------------------------- | +| credential | [Jwt](#Jwt) | +| trustedIssuers | Array.<(CoreDocument\|IToCoreDocument)> | +| options | [JwsVerificationOptions](#JwsVerificationOptions) | + + + +### JwtCredentialValidator.checkExpiresOnOrAfter(credential, timestamp) + +Validate that the credential expires on or after the specified timestamp. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| ---------- | -------------------------------------- | +| credential | [Credential](#Credential) | +| timestamp | [Timestamp](#Timestamp) | + + + +### JwtCredentialValidator.checkIssuedOnOrBefore(credential, timestamp) + +Validate that the credential is issued on or before the specified timestamp. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| ---------- | -------------------------------------- | +| credential | [Credential](#Credential) | +| timestamp | [Timestamp](#Timestamp) | + + + +### JwtCredentialValidator.checkSubjectHolderRelationship(credential, holder, relationship) + +Validate that the relationship between the `holder` and the credential subjects is in accordance with +`relationship`. The `holder` parameter is expected to be the URL of the holder. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| ------------ | -------------------------------------- | +| credential | [Credential](#Credential) | +| holder | string | +| relationship | number | + + + +### JwtCredentialValidator.checkStatus(credential, trustedIssuers, statusCheck) + +Checks whether the credential status has been revoked. + +Only supports `RevocationBitmap2022`. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| -------------- | ---------------------------------------------------------- | +| credential | [Credential](#Credential) | +| trustedIssuers | Array.<(CoreDocument\|IToCoreDocument)> | +| statusCheck | number | + + + +### JwtCredentialValidator.extractIssuer(credential) ⇒ [CoreDID](#CoreDID) + +Utility for extracting the issuer field of a [Credential](#Credential) as a DID. + +### Errors + +Fails if the issuer field is not a valid DID. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| ---------- | -------------------------------------- | +| credential | [Credential](#Credential) | + + + +### JwtCredentialValidator.extractIssuerFromJwt(credential) ⇒ [CoreDID](#CoreDID) + +Utility for extracting the issuer field of a credential in JWT representation as DID. + +# Errors + +If the JWT decoding fails or the issuer field is not a valid DID. + +**Kind**: static method of [JwtCredentialValidator](#JwtCredentialValidator) + +| Param | Type | +| ---------- | ------------------------ | +| credential | [Jwt](#Jwt) | + + + +## JwtDomainLinkageValidator + +A validator for a Domain Linkage Configuration and Credentials. + +**Kind**: global class + +- [JwtDomainLinkageValidator](#JwtDomainLinkageValidator) + - [new JwtDomainLinkageValidator(signatureVerifier)](#new_JwtDomainLinkageValidator_new) + - [.validateLinkage(issuer, configuration, domain, options)](#JwtDomainLinkageValidator+validateLinkage) + - [.validateCredential(issuer, credentialJwt, domain, options)](#JwtDomainLinkageValidator+validateCredential) + + + +### new JwtDomainLinkageValidator(signatureVerifier) + +Creates a new [JwtDomainLinkageValidator](#JwtDomainLinkageValidator). If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + +| Param | Type | +| ----------------- | ------------------------- | +| signatureVerifier | IJwsVerifier | + + + +### jwtDomainLinkageValidator.validateLinkage(issuer, configuration, domain, options) + +Validates the linkage between a domain and a DID. +[DomainLinkageConfiguration](#DomainLinkageConfiguration) is validated according to [DID Configuration Resource Verification](https://identity.foundation/.well-known/resources/did-configuration/#did-configuration-resource-verification). + +Linkage is valid if no error is thrown. + +# Note: + +- Only the [JSON Web Token Proof Format](https://identity.foundation/.well-known/resources/did-configuration/#json-web-token-proof-format) + is supported. +- Only the Credential issued by `issuer` is verified. + +# Errors + +- Semantic structure of `configuration` is invalid. +- `configuration` includes multiple credentials issued by `issuer`. +- Validation of the matched Domain Linkage Credential fails. + +**Kind**: instance method of [JwtDomainLinkageValidator](#JwtDomainLinkageValidator) + +| Param | Type | +| ------------- | ------------------------------------------------------------------------------ | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| configuration | [DomainLinkageConfiguration](#DomainLinkageConfiguration) | +| domain | string | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | + + + +### jwtDomainLinkageValidator.validateCredential(issuer, credentialJwt, domain, options) + +Validates a [Domain Linkage Credential](https://identity.foundation/.well-known/resources/did-configuration/#domain-linkage-credential). + +Error will be thrown in case the validation fails. + +**Kind**: instance method of [JwtDomainLinkageValidator](#JwtDomainLinkageValidator) + +| Param | Type | +| ------------- | ------------------------------------------------------------------------------ | +| issuer | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| credentialJwt | [Jwt](#Jwt) | +| domain | string | +| options | [JwtCredentialValidationOptions](#JwtCredentialValidationOptions) | + + + +## JwtPresentationOptions + +**Kind**: global class + +- [JwtPresentationOptions](#JwtPresentationOptions) + - [new JwtPresentationOptions(options)](#new_JwtPresentationOptions_new) + - _instance_ + - [.toJSON()](#JwtPresentationOptions+toJSON) ⇒ any + - [.clone()](#JwtPresentationOptions+clone) ⇒ [JwtPresentationOptions](#JwtPresentationOptions) + - _static_ + - [.fromJSON(json)](#JwtPresentationOptions.fromJSON) ⇒ [JwtPresentationOptions](#JwtPresentationOptions) + + + +### new JwtPresentationOptions(options) + +Creates a new [JwtPresentationOptions](#JwtPresentationOptions) from the given fields. + +Throws an error if any of the options are invalid. + +| Param | Type | +| ------- | -------------------------------------------------------------- | +| options | IJwtPresentationOptions \| undefined | + + + +### jwtPresentationOptions.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [JwtPresentationOptions](#JwtPresentationOptions) + + + +### jwtPresentationOptions.clone() ⇒ [JwtPresentationOptions](#JwtPresentationOptions) + +Deep clones the object. + +**Kind**: instance method of [JwtPresentationOptions](#JwtPresentationOptions) + + + +### JwtPresentationOptions.fromJSON(json) ⇒ [JwtPresentationOptions](#JwtPresentationOptions) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwtPresentationOptions](#JwtPresentationOptions) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## JwtPresentationValidationOptions + +Options to declare validation criteria when validating presentation. + +**Kind**: global class + +- [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + - [new JwtPresentationValidationOptions(options)](#new_JwtPresentationValidationOptions_new) + - _instance_ + - [.toJSON()](#JwtPresentationValidationOptions+toJSON) ⇒ any + - [.clone()](#JwtPresentationValidationOptions+clone) ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + - _static_ + - [.fromJSON(json)](#JwtPresentationValidationOptions.fromJSON) ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + + + +### new JwtPresentationValidationOptions(options) + +Creates a new [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) from the given fields. + +Throws an error if any of the options are invalid. + +| Param | Type | +| ------- | ------------------------------------------------------------------------ | +| options | IJwtPresentationValidationOptions \| undefined | + + + +### jwtPresentationValidationOptions.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + + + +### jwtPresentationValidationOptions.clone() ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + +Deep clones the object. + +**Kind**: instance method of [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + + + +### JwtPresentationValidationOptions.fromJSON(json) ⇒ [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## JwtPresentationValidator + +**Kind**: global class + +- [JwtPresentationValidator](#JwtPresentationValidator) + - [new JwtPresentationValidator(signatureVerifier)](#new_JwtPresentationValidator_new) + - _instance_ + - [.validate(presentationJwt, holder, validation_options)](#JwtPresentationValidator+validate) ⇒ [DecodedJwtPresentation](#DecodedJwtPresentation) + - _static_ + - [.checkStructure(presentation)](#JwtPresentationValidator.checkStructure) + - [.extractHolder(presentation)](#JwtPresentationValidator.extractHolder) ⇒ [CoreDID](#CoreDID) + + + +### new JwtPresentationValidator(signatureVerifier) + +Creates a new [JwtPresentationValidator](#JwtPresentationValidator). If a `signatureVerifier` is provided it will be used when +verifying decoded JWS signatures, otherwise the default which is only capable of handling the `EdDSA` +algorithm will be used. + +| Param | Type | +| ----------------- | ------------------------- | +| signatureVerifier | IJwsVerifier | + + + +### jwtPresentationValidator.validate(presentationJwt, holder, validation_options) ⇒ [DecodedJwtPresentation](#DecodedJwtPresentation) + +Validates a [Presentation](#Presentation) encoded as a [Jwt](#Jwt). + +The following properties are validated according to `options`: + +- the JWT can be decoded into a semantically valid presentation. +- the expiration and issuance date contained in the JWT claims. +- the holder's signature. + +Validation is done with respect to the properties set in `options`. + +# Warning + +- This method does NOT validate the constituent credentials and therefore also not the relationship between the + credentials' subjects and the presentation holder. This can be done with [JwtCredentialValidationOptions](#JwtCredentialValidationOptions). +- The lack of an error returned from this method is in of itself not enough to conclude that the presentation can + be trusted. This section contains more information on additional checks that should be carried out before and + after calling this method. + +## The state of the supplied DID Documents + +The caller must ensure that the DID Documents in `holder` are up-to-date. + +# Errors + +An error is returned whenever a validated condition is not satisfied or when decoding fails. + +**Kind**: instance method of [JwtPresentationValidator](#JwtPresentationValidator) + +| Param | Type | +| ------------------ | ---------------------------------------------------------------------------------- | +| presentationJwt | [Jwt](#Jwt) | +| holder | [CoreDocument](#CoreDocument) \| IToCoreDocument | +| validation_options | [JwtPresentationValidationOptions](#JwtPresentationValidationOptions) | + + + +### JwtPresentationValidator.checkStructure(presentation) + +Validates the semantic structure of the [Presentation](#Presentation). + +**Kind**: static method of [JwtPresentationValidator](#JwtPresentationValidator) + +| Param | Type | +| ------------ | ------------------------------------------ | +| presentation | [Presentation](#Presentation) | + + + +### JwtPresentationValidator.extractHolder(presentation) ⇒ [CoreDID](#CoreDID) + +Attempt to extract the holder of the presentation. + +# Errors + +- If deserialization/decoding of the presentation fails. +- If the holder can't be parsed as DIDs. + +**Kind**: static method of [JwtPresentationValidator](#JwtPresentationValidator) + +| Param | Type | +| ------------ | ------------------------ | +| presentation | [Jwt](#Jwt) | + + + +## LinkedDomainService + +**Kind**: global class + +- [LinkedDomainService](#LinkedDomainService) + - [new LinkedDomainService(options)](#new_LinkedDomainService_new) + - _instance_ + - [.domains()](#LinkedDomainService+domains) ⇒ Array.<string> + - [.toService()](#LinkedDomainService+toService) ⇒ [Service](#Service) + - [.clone()](#LinkedDomainService+clone) ⇒ [LinkedDomainService](#LinkedDomainService) + - _static_ + - [.fromService(service)](#LinkedDomainService.fromService) ⇒ [LinkedDomainService](#LinkedDomainService) + - [.isValid(service)](#LinkedDomainService.isValid) ⇒ boolean + + + +### new LinkedDomainService(options) + +Constructs a new [LinkedDomainService](#LinkedDomainService) that wraps a spec compliant [Linked Domain Service Endpoint](https://identity.foundation/.well-known/resources/did-configuration/#linked-domain-service-endpoint). + +Domain URLs must include the `https` scheme in order to pass the domain linkage validation. + +| Param | Type | +| ------- | --------------------------------- | +| options | ILinkedDomainService | + + + +### linkedDomainService.domains() ⇒ Array.<string> + +Returns the domains contained in the Linked Domain Service. + +**Kind**: instance method of [LinkedDomainService](#LinkedDomainService) + + + +### linkedDomainService.toService() ⇒ [Service](#Service) + +Returns the inner service which can be added to a DID Document. + +**Kind**: instance method of [LinkedDomainService](#LinkedDomainService) + + + +### linkedDomainService.clone() ⇒ [LinkedDomainService](#LinkedDomainService) + +Deep clones the object. + +**Kind**: instance method of [LinkedDomainService](#LinkedDomainService) + + + +### LinkedDomainService.fromService(service) ⇒ [LinkedDomainService](#LinkedDomainService) + +Creates a new [LinkedDomainService](#LinkedDomainService) from a [Service](#Service). + +# Error + +Errors if `service` is not a valid Linked Domain Service. + +**Kind**: static method of [LinkedDomainService](#LinkedDomainService) + +| Param | Type | +| ------- | -------------------------------- | +| service | [Service](#Service) | + + + +### LinkedDomainService.isValid(service) ⇒ boolean + +Returns `true` if a [Service](#Service) is a valid Linked Domain Service. + +**Kind**: static method of [LinkedDomainService](#LinkedDomainService) + +| Param | Type | +| ------- | -------------------------------- | +| service | [Service](#Service) | + + + +## MethodData + +Supported verification method data formats. + +**Kind**: global class + +- [MethodData](#MethodData) + - _instance_ + - [.tryDecode()](#MethodData+tryDecode) ⇒ Uint8Array + - [.tryPublicKeyJwk()](#MethodData+tryPublicKeyJwk) ⇒ [Jwk](#Jwk) + - [.toJSON()](#MethodData+toJSON) ⇒ any + - [.clone()](#MethodData+clone) ⇒ [MethodData](#MethodData) + - _static_ + - [.newBase58(data)](#MethodData.newBase58) ⇒ [MethodData](#MethodData) + - [.newMultibase(data)](#MethodData.newMultibase) ⇒ [MethodData](#MethodData) + - [.newJwk(key)](#MethodData.newJwk) ⇒ [MethodData](#MethodData) + - [.fromJSON(json)](#MethodData.fromJSON) ⇒ [MethodData](#MethodData) + + + +### methodData.tryDecode() ⇒ Uint8Array + +Returns a `Uint8Array` containing the decoded bytes of the [MethodData](#MethodData). + +This is generally a public key identified by a [MethodData](#MethodData) value. + +### Errors + +Decoding can fail if [MethodData](#MethodData) has invalid content or cannot be +represented as a vector of bytes. + +**Kind**: instance method of [MethodData](#MethodData) + + + +### methodData.tryPublicKeyJwk() ⇒ [Jwk](#Jwk) + +Returns the wrapped [Jwk](#Jwk) if the format is `PublicKeyJwk`. + +**Kind**: instance method of [MethodData](#MethodData) + + + +### methodData.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [MethodData](#MethodData) + + + +### methodData.clone() ⇒ [MethodData](#MethodData) + +Deep clones the object. + +**Kind**: instance method of [MethodData](#MethodData) + + + +### MethodData.newBase58(data) ⇒ [MethodData](#MethodData) + +Creates a new [MethodData](#MethodData) variant with Base58-BTC encoded content. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| ----- | ----------------------- | +| data | Uint8Array | + + + +### MethodData.newMultibase(data) ⇒ [MethodData](#MethodData) + +Creates a new [MethodData](#MethodData) variant with Multibase-encoded content. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| ----- | ----------------------- | +| data | Uint8Array | + + + +### MethodData.newJwk(key) ⇒ [MethodData](#MethodData) + +Creates a new [MethodData](#MethodData) variant consisting of the given `key`. + +### Errors + +An error is thrown if the given `key` contains any private components. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| ----- | ------------------------ | +| key | [Jwk](#Jwk) | + + + +### MethodData.fromJSON(json) ⇒ [MethodData](#MethodData) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [MethodData](#MethodData) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## MethodDigest + +Unique identifier of a [VerificationMethod](#VerificationMethod). + +NOTE: +This class does not have a JSON representation, +use the methods `pack` and `unpack` instead. + +**Kind**: global class + +- [MethodDigest](#MethodDigest) + - [new MethodDigest(verification_method)](#new_MethodDigest_new) + - _instance_ + - [.pack()](#MethodDigest+pack) ⇒ Uint8Array + - [.clone()](#MethodDigest+clone) ⇒ [MethodDigest](#MethodDigest) + - _static_ + - [.unpack(bytes)](#MethodDigest.unpack) ⇒ [MethodDigest](#MethodDigest) + + + +### new MethodDigest(verification_method) + +| Param | Type | +| ------------------- | ------------------------------------------------------ | +| verification_method | [VerificationMethod](#VerificationMethod) | + + + +### methodDigest.pack() ⇒ Uint8Array + +Packs [MethodDigest](#MethodDigest) into bytes. + +**Kind**: instance method of [MethodDigest](#MethodDigest) + + + +### methodDigest.clone() ⇒ [MethodDigest](#MethodDigest) + +Deep clones the object. + +**Kind**: instance method of [MethodDigest](#MethodDigest) + + + +### MethodDigest.unpack(bytes) ⇒ [MethodDigest](#MethodDigest) + +Unpacks bytes into [MethodDigest](#MethodDigest). + +**Kind**: static method of [MethodDigest](#MethodDigest) + +| Param | Type | +| ----- | ----------------------- | +| bytes | Uint8Array | + + + +## MethodScope + +Supported verification method types. + +**Kind**: global class + +- [MethodScope](#MethodScope) + - _instance_ + - [.toString()](#MethodScope+toString) ⇒ string + - [.toJSON()](#MethodScope+toJSON) ⇒ any + - [.clone()](#MethodScope+clone) ⇒ [MethodScope](#MethodScope) + - _static_ + - [.VerificationMethod()](#MethodScope.VerificationMethod) ⇒ [MethodScope](#MethodScope) + - [.Authentication()](#MethodScope.Authentication) ⇒ [MethodScope](#MethodScope) + - [.AssertionMethod()](#MethodScope.AssertionMethod) ⇒ [MethodScope](#MethodScope) + - [.KeyAgreement()](#MethodScope.KeyAgreement) ⇒ [MethodScope](#MethodScope) + - [.CapabilityDelegation()](#MethodScope.CapabilityDelegation) ⇒ [MethodScope](#MethodScope) + - [.CapabilityInvocation()](#MethodScope.CapabilityInvocation) ⇒ [MethodScope](#MethodScope) + - [.fromJSON(json)](#MethodScope.fromJSON) ⇒ [MethodScope](#MethodScope) + + + +### methodScope.toString() ⇒ string + +Returns the [MethodScope](#MethodScope) as a string. + +**Kind**: instance method of [MethodScope](#MethodScope) + + + +### methodScope.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [MethodScope](#MethodScope) + + + +### methodScope.clone() ⇒ [MethodScope](#MethodScope) + +Deep clones the object. + +**Kind**: instance method of [MethodScope](#MethodScope) + + + +### MethodScope.VerificationMethod() ⇒ [MethodScope](#MethodScope) + +**Kind**: static method of [MethodScope](#MethodScope) + + + +### MethodScope.Authentication() ⇒ [MethodScope](#MethodScope) + +**Kind**: static method of [MethodScope](#MethodScope) + + + +### MethodScope.AssertionMethod() ⇒ [MethodScope](#MethodScope) + +**Kind**: static method of [MethodScope](#MethodScope) + + + +### MethodScope.KeyAgreement() ⇒ [MethodScope](#MethodScope) + +**Kind**: static method of [MethodScope](#MethodScope) + + + +### MethodScope.CapabilityDelegation() ⇒ [MethodScope](#MethodScope) + +**Kind**: static method of [MethodScope](#MethodScope) + + + +### MethodScope.CapabilityInvocation() ⇒ [MethodScope](#MethodScope) + +**Kind**: static method of [MethodScope](#MethodScope) + + + +### MethodScope.fromJSON(json) ⇒ [MethodScope](#MethodScope) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [MethodScope](#MethodScope) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## MethodType + +Supported verification method types. + +**Kind**: global class + +- [MethodType](#MethodType) + - _instance_ + - [.toString()](#MethodType+toString) ⇒ string + - [.toJSON()](#MethodType+toJSON) ⇒ any + - [.clone()](#MethodType+clone) ⇒ [MethodType](#MethodType) + - _static_ + - [.Ed25519VerificationKey2018()](#MethodType.Ed25519VerificationKey2018) ⇒ [MethodType](#MethodType) + - [.X25519KeyAgreementKey2019()](#MethodType.X25519KeyAgreementKey2019) ⇒ [MethodType](#MethodType) + - [.JsonWebKey()](#MethodType.JsonWebKey) ⇒ [MethodType](#MethodType) + - [.fromJSON(json)](#MethodType.fromJSON) ⇒ [MethodType](#MethodType) + + + +### methodType.toString() ⇒ string + +Returns the [MethodType](#MethodType) as a string. + +**Kind**: instance method of [MethodType](#MethodType) + + + +### methodType.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [MethodType](#MethodType) + + + +### methodType.clone() ⇒ [MethodType](#MethodType) + +Deep clones the object. + +**Kind**: instance method of [MethodType](#MethodType) + + + +### MethodType.Ed25519VerificationKey2018() ⇒ [MethodType](#MethodType) + +**Kind**: static method of [MethodType](#MethodType) + + + +### MethodType.X25519KeyAgreementKey2019() ⇒ [MethodType](#MethodType) + +**Kind**: static method of [MethodType](#MethodType) + + + +### MethodType.JsonWebKey() ⇒ [MethodType](#MethodType) + +A verification method for use with JWT verification as prescribed by the [Jwk](#Jwk) +in the `publicKeyJwk` entry. + +**Kind**: static method of [MethodType](#MethodType) + + + +### MethodType.fromJSON(json) ⇒ [MethodType](#MethodType) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [MethodType](#MethodType) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## Presentation + +**Kind**: global class + +- [Presentation](#Presentation) + - [new Presentation(values)](#new_Presentation_new) + - _instance_ + - [.context()](#Presentation+context) ⇒ Array.<(string\|Record.<string, any>)> + - [.id()](#Presentation+id) ⇒ string \| undefined + - [.type()](#Presentation+type) ⇒ Array.<string> + - [.verifiableCredential()](#Presentation+verifiableCredential) ⇒ [Array.<UnknownCredential>](#UnknownCredential) + - [.holder()](#Presentation+holder) ⇒ string + - [.refreshService()](#Presentation+refreshService) ⇒ Array.<RefreshService> + - [.termsOfUse()](#Presentation+termsOfUse) ⇒ Array.<Policy> + - [.proof()](#Presentation+proof) ⇒ [Proof](#Proof) \| undefined + - [.setProof(proof)](#Presentation+setProof) + - [.properties()](#Presentation+properties) ⇒ Map.<string, any> + - [.toJSON()](#Presentation+toJSON) ⇒ any + - [.clone()](#Presentation+clone) ⇒ [Presentation](#Presentation) + - _static_ + - [.BaseContext()](#Presentation.BaseContext) ⇒ string + - [.BaseType()](#Presentation.BaseType) ⇒ string + - [.fromJSON(json)](#Presentation.fromJSON) ⇒ [Presentation](#Presentation) + + + +### new Presentation(values) + +Constructs a new presentation. + +| Param | Type | +| ------ | -------------------------- | +| values | IPresentation | + + + +### presentation.context() ⇒ Array.<(string\|Record.<string, any>)> + +Returns a copy of the JSON-LD context(s) applicable to the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.id() ⇒ string \| undefined + +Returns a copy of the unique `URI` identifying the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.type() ⇒ Array.<string> + +Returns a copy of the URIs defining the type of the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.verifiableCredential() ⇒ [Array.<UnknownCredential>](#UnknownCredential) + +Returns the JWT credentials expressing the claims of the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.holder() ⇒ string + +Returns a copy of the URI of the entity that generated the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.refreshService() ⇒ Array.<RefreshService> + +Returns a copy of the service(s) used to refresh an expired [Credential](#Credential) in the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.termsOfUse() ⇒ Array.<Policy> + +Returns a copy of the terms-of-use specified by the presentation holder + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.proof() ⇒ [Proof](#Proof) \| undefined + +Optional cryptographic proof, unrelated to JWT. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.setProof(proof) + +Sets the proof property of the [Presentation](#Presentation). + +Note that this proof is not related to JWT. + +**Kind**: instance method of [Presentation](#Presentation) + +| Param | Type | +| ----- | ------------------------------------------------------ | +| proof | [Proof](#Proof) \| undefined | + + + +### presentation.properties() ⇒ Map.<string, any> + +Returns a copy of the miscellaneous properties on the presentation. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### presentation.clone() ⇒ [Presentation](#Presentation) + +Deep clones the object. + +**Kind**: instance method of [Presentation](#Presentation) + + + +### Presentation.BaseContext() ⇒ string + +Returns the base JSON-LD context. + +**Kind**: static method of [Presentation](#Presentation) + + + +### Presentation.BaseType() ⇒ string + +Returns the base type. + +**Kind**: static method of [Presentation](#Presentation) + + + +### Presentation.fromJSON(json) ⇒ [Presentation](#Presentation) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Presentation](#Presentation) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## Proof + +Represents a cryptographic proof that can be used to validate verifiable credentials and +presentations. + +This representation does not inherently implement any standard; instead, it +can be utilized to implement standards or user-defined proofs. The presence of the +`type` field is necessary to accommodate different types of cryptographic proofs. + +Note that this proof is not related to JWT and can be used in combination or as an alternative +to it. + +**Kind**: global class + +- [Proof](#Proof) + - [new Proof(type\_, properties)](#new_Proof_new) + - _instance_ + - [.type()](#Proof+type) ⇒ string + - [.properties()](#Proof+properties) ⇒ any + - [.toJSON()](#Proof+toJSON) ⇒ any + - [.clone()](#Proof+clone) ⇒ [Proof](#Proof) + - _static_ + - [.fromJSON(json)](#Proof.fromJSON) ⇒ [Proof](#Proof) + + + +### new Proof(type\_, properties) + +| Param | Type | +| ---------- | ------------------- | +| type\_ | string | +| properties | any | + + + +### proof.type() ⇒ string + +Returns the type of proof. + +**Kind**: instance method of [Proof](#Proof) + + + +### proof.properties() ⇒ any + +Returns the properties of the proof. + +**Kind**: instance method of [Proof](#Proof) + + + +### proof.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Proof](#Proof) + + + +### proof.clone() ⇒ [Proof](#Proof) + +Deep clones the object. + +**Kind**: instance method of [Proof](#Proof) + + + +### Proof.fromJSON(json) ⇒ [Proof](#Proof) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Proof](#Proof) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## Resolver + +Convenience type for resolving DID documents from different DID methods. + +Also provides methods for resolving DID Documents associated with +verifiable [Credential](#Credential)s and [Presentation](#Presentation)s. + +# Configuration + +The resolver will only be able to resolve DID documents for methods it has been configured for in the constructor. + +**Kind**: global class + +- [Resolver](#Resolver) + - [new Resolver(config)](#new_Resolver_new) + - [.resolve(did)](#Resolver+resolve) ⇒ Promise.<(CoreDocument\|IToCoreDocument)> + - [.resolveMultiple(dids)](#Resolver+resolveMultiple) ⇒ Promise.<Array.<(CoreDocument\|IToCoreDocument)>> + + + +### new Resolver(config) + +Constructs a new [Resolver](#Resolver). + +# Errors + +If both a `client` is given and the `handlers` map contains the "iota" key the construction process +will throw an error because the handler for the "iota" method then becomes ambiguous. + +| Param | Type | +| ------ | --------------------------- | +| config | ResolverConfig | + + + +### resolver.resolve(did) ⇒ Promise.<(CoreDocument\|IToCoreDocument)> + +Fetches the DID Document of the given DID. + +### Errors + +Errors if the resolver has not been configured to handle the method +corresponding to the given DID or the resolution process itself fails. + +**Kind**: instance method of [Resolver](#Resolver) + +| Param | Type | +| ----- | ------------------- | +| did | string | + + + +### resolver.resolveMultiple(dids) ⇒ Promise.<Array.<(CoreDocument\|IToCoreDocument)>> + +Concurrently fetches the DID Documents of the multiple given DIDs. + +# Errors + +- If the resolver has not been configured to handle the method of any of the given DIDs. +- If the resolution process of any DID fails. + +## Note + +- The order of the documents in the returned array matches that in `dids`. +- If `dids` contains duplicates, these will be resolved only once and the resolved document + is copied into the returned array to match the order of `dids`. + +**Kind**: instance method of [Resolver](#Resolver) + +| Param | Type | +| ----- | --------------------------------- | +| dids | Array.<string> | + + + +## RevocationBitmap + +A compressed bitmap for managing credential revocation. + +**Kind**: global class + +- [RevocationBitmap](#RevocationBitmap) + - [new RevocationBitmap()](#new_RevocationBitmap_new) + - _instance_ + - [.isRevoked(index)](#RevocationBitmap+isRevoked) ⇒ boolean + - [.revoke(index)](#RevocationBitmap+revoke) ⇒ boolean + - [.unrevoke(index)](#RevocationBitmap+unrevoke) ⇒ boolean + - [.len()](#RevocationBitmap+len) ⇒ number + - [.toService(serviceId)](#RevocationBitmap+toService) ⇒ [Service](#Service) + - _static_ + - [.type()](#RevocationBitmap.type) ⇒ string + - [.fromEndpoint(service)](#RevocationBitmap.fromEndpoint) ⇒ [RevocationBitmap](#RevocationBitmap) + + + +### new RevocationBitmap() + +Creates a new [RevocationBitmap](#RevocationBitmap) instance. + + + +### revocationBitmap.isRevoked(index) ⇒ boolean + +Returns `true` if the credential at the given `index` is revoked. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| ----- | ------------------- | +| index | number | + + + +### revocationBitmap.revoke(index) ⇒ boolean + +Mark the given index as revoked. + +Returns true if the index was absent from the set. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| ----- | ------------------- | +| index | number | + + + +### revocationBitmap.unrevoke(index) ⇒ boolean + +Mark the index as not revoked. + +Returns true if the index was present in the set. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| ----- | ------------------- | +| index | number | + + + +### revocationBitmap.len() ⇒ number + +Returns the number of revoked credentials. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + + + +### revocationBitmap.toService(serviceId) ⇒ [Service](#Service) + +Return a `Service` with: + +- the service's id set to `serviceId`, +- of type `RevocationBitmap2022`, +- and with the bitmap embedded in a data url in the service's endpoint. + +**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| --------- | ------------------------------ | +| serviceId | [DIDUrl](#DIDUrl) | + + + +### RevocationBitmap.type() ⇒ string + +The name of the service type. + +**Kind**: static method of [RevocationBitmap](#RevocationBitmap) + + + +### RevocationBitmap.fromEndpoint(service) ⇒ [RevocationBitmap](#RevocationBitmap) + +Try to construct a [RevocationBitmap](#RevocationBitmap) from a service +if it is a valid Revocation Bitmap Service. + +**Kind**: static method of [RevocationBitmap](#RevocationBitmap) + +| Param | Type | +| ------- | -------------------------------- | +| service | [Service](#Service) | + + + +## Service + +A DID Document Service used to enable trusted interactions associated with a DID subject. + +**Kind**: global class + +- [Service](#Service) + - [new Service(service)](#new_Service_new) + - _instance_ + - [.id()](#Service+id) ⇒ [DIDUrl](#DIDUrl) + - [.type()](#Service+type) ⇒ Array.<string> + - [.serviceEndpoint()](#Service+serviceEndpoint) ⇒ string \| Array.<string> \| Map.<string, Array.<string>> + - [.properties()](#Service+properties) ⇒ Map.<string, any> + - [.toJSON()](#Service+toJSON) ⇒ any + - [.clone()](#Service+clone) ⇒ [Service](#Service) + - _static_ + - [.fromJSON(json)](#Service.fromJSON) ⇒ [Service](#Service) + + + +### new Service(service) + +| Param | Type | +| ------- | --------------------- | +| service | IService | + + + +### service.id() ⇒ [DIDUrl](#DIDUrl) + +Returns a copy of the [Service](#Service) id. + +**Kind**: instance method of [Service](#Service) + + + +### service.type() ⇒ Array.<string> + +Returns a copy of the [Service](#Service) type. + +**Kind**: instance method of [Service](#Service) + + + +### service.serviceEndpoint() ⇒ string \| Array.<string> \| Map.<string, Array.<string>> + +Returns a copy of the [Service](#Service) endpoint. + +**Kind**: instance method of [Service](#Service) + + + +### service.properties() ⇒ Map.<string, any> + +Returns a copy of the custom properties on the [Service](#Service). + +**Kind**: instance method of [Service](#Service) + + + +### service.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Service](#Service) + + + +### service.clone() ⇒ [Service](#Service) + +Deep clones the object. + +**Kind**: instance method of [Service](#Service) + + + +### Service.fromJSON(json) ⇒ [Service](#Service) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Service](#Service) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## Storage + +A type wrapping a `JwkStorage` and `KeyIdStorage` that should always be used together when +working with storage backed DID documents. + +**Kind**: global class + +- [Storage](#Storage) + - [new Storage(jwkStorage, keyIdStorage)](#new_Storage_new) + - [.keyIdStorage()](#Storage+keyIdStorage) ⇒ KeyIdStorage + - [.keyStorage()](#Storage+keyStorage) ⇒ JwkStorage + + + +### new Storage(jwkStorage, keyIdStorage) + +Constructs a new `Storage`. + +| Param | Type | +| ------------ | ------------------------- | +| jwkStorage | JwkStorage | +| keyIdStorage | KeyIdStorage | + + + +### storage.keyIdStorage() ⇒ KeyIdStorage + +Obtain the wrapped `KeyIdStorage`. + +**Kind**: instance method of [Storage](#Storage) + + + +### storage.keyStorage() ⇒ JwkStorage + +Obtain the wrapped `JwkStorage`. + +**Kind**: instance method of [Storage](#Storage) + + + +## Timestamp + +**Kind**: global class + +- [Timestamp](#Timestamp) + - [new Timestamp()](#new_Timestamp_new) + - _instance_ + - [.toRFC3339()](#Timestamp+toRFC3339) ⇒ string + - [.checkedAdd(duration)](#Timestamp+checkedAdd) ⇒ [Timestamp](#Timestamp) \| undefined + - [.checkedSub(duration)](#Timestamp+checkedSub) ⇒ [Timestamp](#Timestamp) \| undefined + - [.toJSON()](#Timestamp+toJSON) ⇒ any + - _static_ + - [.parse(input)](#Timestamp.parse) ⇒ [Timestamp](#Timestamp) + - [.nowUTC()](#Timestamp.nowUTC) ⇒ [Timestamp](#Timestamp) + - [.fromJSON(json)](#Timestamp.fromJSON) ⇒ [Timestamp](#Timestamp) + + + +### new Timestamp() + +Creates a new [Timestamp](#Timestamp) with the current date and time. + + + +### timestamp.toRFC3339() ⇒ string + +Returns the [Timestamp](#Timestamp) as an RFC 3339 `String`. + +**Kind**: instance method of [Timestamp](#Timestamp) + + + +### timestamp.checkedAdd(duration) ⇒ [Timestamp](#Timestamp) \| undefined + +Computes `self + duration` + +Returns `null` if the operation leads to a timestamp not in the valid range for [RFC 3339](https://tools.ietf.org/html/rfc3339). + +**Kind**: instance method of [Timestamp](#Timestamp) + +| Param | Type | +| -------- | ---------------------------------- | +| duration | [Duration](#Duration) | + + + +### timestamp.checkedSub(duration) ⇒ [Timestamp](#Timestamp) \| undefined + +Computes `self - duration` + +Returns `null` if the operation leads to a timestamp not in the valid range for [RFC 3339](https://tools.ietf.org/html/rfc3339). + +**Kind**: instance method of [Timestamp](#Timestamp) + +| Param | Type | +| -------- | ---------------------------------- | +| duration | [Duration](#Duration) | + + + +### timestamp.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [Timestamp](#Timestamp) + + + +### Timestamp.parse(input) ⇒ [Timestamp](#Timestamp) + +Parses a [Timestamp](#Timestamp) from the provided input string. + +**Kind**: static method of [Timestamp](#Timestamp) + +| Param | Type | +| ----- | ------------------- | +| input | string | + + + +### Timestamp.nowUTC() ⇒ [Timestamp](#Timestamp) + +Creates a new [Timestamp](#Timestamp) with the current date and time. + +**Kind**: static method of [Timestamp](#Timestamp) + + + +### Timestamp.fromJSON(json) ⇒ [Timestamp](#Timestamp) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [Timestamp](#Timestamp) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## UnknownCredential + +**Kind**: global class + +- [UnknownCredential](#UnknownCredential) + - _instance_ + - [.tryIntoJwt()](#UnknownCredential+tryIntoJwt) ⇒ [Jwt](#Jwt) \| undefined + - [.tryIntoCredential()](#UnknownCredential+tryIntoCredential) ⇒ [Credential](#Credential) \| undefined + - [.tryIntoRaw()](#UnknownCredential+tryIntoRaw) ⇒ Record.<string, any> \| undefined + - [.toJSON()](#UnknownCredential+toJSON) ⇒ any + - [.clone()](#UnknownCredential+clone) ⇒ [UnknownCredential](#UnknownCredential) + - _static_ + - [.fromJSON(json)](#UnknownCredential.fromJSON) ⇒ [UnknownCredential](#UnknownCredential) + + + +### unknownCredential.tryIntoJwt() ⇒ [Jwt](#Jwt) \| undefined + +Returns a [Jwt](#Jwt) if the credential is of type string, `undefined` otherwise. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + + +### unknownCredential.tryIntoCredential() ⇒ [Credential](#Credential) \| undefined + +Returns a [Credential](#Credential) if the credential is of said type, `undefined` otherwise. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + + +### unknownCredential.tryIntoRaw() ⇒ Record.<string, any> \| undefined + +Returns the contained value as an Object, if it can be converted, `undefined` otherwise. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + + +### unknownCredential.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + + +### unknownCredential.clone() ⇒ [UnknownCredential](#UnknownCredential) + +Deep clones the object. + +**Kind**: instance method of [UnknownCredential](#UnknownCredential) + + + +### UnknownCredential.fromJSON(json) ⇒ [UnknownCredential](#UnknownCredential) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [UnknownCredential](#UnknownCredential) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## VerificationMethod + +A DID Document Verification Method. + +**Kind**: global class + +- [VerificationMethod](#VerificationMethod) + - _instance_ + - [.id()](#VerificationMethod+id) ⇒ [DIDUrl](#DIDUrl) + - [.setId(id)](#VerificationMethod+setId) + - [.controller()](#VerificationMethod+controller) ⇒ [CoreDID](#CoreDID) + - [.setController(did)](#VerificationMethod+setController) + - [.type()](#VerificationMethod+type) ⇒ [MethodType](#MethodType) + - [.setType(type\_)](#VerificationMethod+setType) + - [.data()](#VerificationMethod+data) ⇒ [MethodData](#MethodData) + - [.setData(data)](#VerificationMethod+setData) + - [.properties()](#VerificationMethod+properties) ⇒ Map.<string, any> + - [.setPropertyUnchecked(key, value)](#VerificationMethod+setPropertyUnchecked) + - [.toJSON()](#VerificationMethod+toJSON) ⇒ any + - [.clone()](#VerificationMethod+clone) ⇒ [VerificationMethod](#VerificationMethod) + - _static_ + - [.newFromJwk(did, key, fragment)](#VerificationMethod.newFromJwk) ⇒ [VerificationMethod](#VerificationMethod) + - [.fromJSON(json)](#VerificationMethod.fromJSON) ⇒ [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.id() ⇒ [DIDUrl](#DIDUrl) + +Returns a copy of the [DIDUrl](#DIDUrl) of the [VerificationMethod](#VerificationMethod)'s `id`. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.setId(id) + +Sets the id of the [VerificationMethod](#VerificationMethod). + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| ----- | ------------------------------ | +| id | [DIDUrl](#DIDUrl) | + + + +### verificationMethod.controller() ⇒ [CoreDID](#CoreDID) + +Returns a copy of the `controller` `DID` of the [VerificationMethod](#VerificationMethod). + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.setController(did) + +Sets the `controller` `DID` of the [VerificationMethod](#VerificationMethod) object. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| ----- | -------------------------------- | +| did | [CoreDID](#CoreDID) | + + + +### verificationMethod.type() ⇒ [MethodType](#MethodType) + +Returns a copy of the [VerificationMethod](#VerificationMethod) type. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.setType(type\_) + +Sets the [VerificationMethod](#VerificationMethod) type. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| ------ | -------------------------------------- | +| type\_ | [MethodType](#MethodType) | + + + +### verificationMethod.data() ⇒ [MethodData](#MethodData) + +Returns a copy of the [VerificationMethod](#VerificationMethod) public key data. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.setData(data) + +Sets [VerificationMethod](#VerificationMethod) public key data. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| ----- | -------------------------------------- | +| data | [MethodData](#MethodData) | + + + +### verificationMethod.properties() ⇒ Map.<string, any> + +Get custom properties of the Verification Method. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.setPropertyUnchecked(key, value) + +Adds a custom property to the Verification Method. +If the value is set to `null`, the custom property will be removed. + +### WARNING + +This method can overwrite existing properties like `id` and result +in an invalid Verification Method. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| ----- | ------------------- | +| key | string | +| value | any | + + + +### verificationMethod.toJSON() ⇒ any + +Serializes this to a JSON object. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + + +### verificationMethod.clone() ⇒ [VerificationMethod](#VerificationMethod) + +Deep clones the object. + +**Kind**: instance method of [VerificationMethod](#VerificationMethod) + + + +### VerificationMethod.newFromJwk(did, key, fragment) ⇒ [VerificationMethod](#VerificationMethod) + +Creates a new [VerificationMethod](#VerificationMethod) from the given `did` and [Jwk](#Jwk). If `fragment` is not given +the `kid` value of the given `key` will be used, if present, otherwise an error is returned. + +### Recommendations + +The following recommendations are essentially taken from the `publicKeyJwk` description from the [DID specification](https://www.w3.org/TR/did-core/#dfn-publickeyjwk): + +- It is recommended that verification methods that use `Jwks` to represent their public keys use the value of + `kid` as their fragment identifier. This is + done automatically if `None` is passed in as the fragment. +- It is recommended that [Jwk](#Jwk) kid values are set to the public key fingerprint. + +**Kind**: static method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| -------- | ----------------------------------------------------------- | +| did | [CoreDID](#CoreDID) \| IToCoreDID | +| key | [Jwk](#Jwk) | +| fragment | string \| undefined | + + + +### VerificationMethod.fromJSON(json) ⇒ [VerificationMethod](#VerificationMethod) + +Deserializes an instance from a JSON object. + +**Kind**: static method of [VerificationMethod](#VerificationMethod) + +| Param | Type | +| ----- | ---------------- | +| json | any | + + + +## StatusCheck + +Controls validation behaviour when checking whether or not a credential has been revoked by its +[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status). + +**Kind**: global variable + + + +## Strict + +Validate the status if supported, reject any unsupported +[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) types. + +Only `RevocationBitmap2022` is currently supported. + +This is the default. + +**Kind**: global variable + + + +## SkipUnsupported + +Validate the status if supported, skip any unsupported +[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) types. + +**Kind**: global variable + + + +## SkipAll + +Skip all status checks. + +**Kind**: global variable + + + +## SubjectHolderRelationship + +Declares how credential subjects must relate to the presentation holder. + +See also the [Subject-Holder Relationship](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) section of the specification. + +**Kind**: global variable + + + +## AlwaysSubject + +The holder must always match the subject on all credentials, regardless of their [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. +This variant is the default. + +**Kind**: global variable + + + +## SubjectOnNonTransferable + +The holder must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. + +**Kind**: global variable + + + +## Any + +The holder is not required to have any kind of relationship to any credential subject. + +**Kind**: global variable + + + +## FailFast + +Declares when validation should return if an error occurs. + +**Kind**: global variable + + + +## AllErrors + +Return all errors that occur during validation. + +**Kind**: global variable + + + +## FirstError + +Return after the first error occurs. + +**Kind**: global variable + + + +## StateMetadataEncoding + +**Kind**: global variable + + + +## MethodRelationship + +**Kind**: global variable + + + +## verifyEd25519(alg, signingInput, decodedSignature, publicKey) + +Verify a JWS signature secured with the `EdDSA` algorithm and curve `Ed25519`. + +This function is useful when one is composing a `IJwsVerifier` that delegates +`EdDSA` verification with curve `Ed25519` to this function. + +# Warning + +This function does not check whether `alg = EdDSA` in the protected header. Callers are expected to assert this +prior to calling the function. + +**Kind**: global function + +| Param | Type | +| ---------------- | ------------------------- | +| alg | JwsAlgorithm | +| signingInput | Uint8Array | +| decodedSignature | Uint8Array | +| publicKey | [Jwk](#Jwk) | + + + +## start() + +Initializes the console error panic hook for better error messages + +**Kind**: global function + + + +## encodeB64(data) ⇒ string + +Encode the given bytes in url-safe base64. + +**Kind**: global function + +| Param | Type | +| ----- | ----------------------- | +| data | Uint8Array | + + + +## decodeB64(data) ⇒ Uint8Array + +Decode the given url-safe base64-encoded slice into its raw bytes. + +**Kind**: global function + +| Param | Type | +| ----- | ----------------------- | +| data | Uint8Array | diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx new file mode 100644 index 00000000000..87787af978b --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx @@ -0,0 +1,263 @@ +--- +title: IOTA DID Method Specification v1.0 +sidebar_label: DID Method +description: How IOTA Identity implements the Decentralized Identifiers Standard on the IOTA Tangle. +image: /img/Identity_icon.png +keywords: + - DID + - specs + - specifications + - Decentralized Identifiers + - Tangle + - format +--- + +# IOTA DID Method Specification v1.0 + +2023-08-23 + +## Abstract + +The IOTA DID Method Specification describes a method of implementing the [Decentralized Identifiers](https://www.w3.org/TR/did-core/) (DID) standard on [IOTA](https://iota.org), a Distributed Ledger Technology (DLT). It conforms to the [DID specification v1.0](https://www.w3.org/TR/did-core/) and describes how to perform Create, Read, Update and Delete (CRUD) operations for IOTA DID Documents using unspent transaction outputs (_UTXO_) on the IOTA and [Shimmer](https://shimmer.network/) networks, introduced with the [Stardust upgrade](https://blog.shimmer.network/stardust-upgrade-in-a-nutshell/). + +## Data Types & Subschema Notation + +Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/main/tips/TIP-0021/tip-0021.md). + +## Introduction + +### UTXO Ledger + +The unspent transaction output ([UTXO](/tips/tips/TIP-0020/)) model defines a ledger state which is comprised of unspent outputs. Outputs are created by a transaction consuming outputs of previous transactions as inputs. The Stardust version of the protocol defines several output types, the relevant ones for the IOTA DID Method are: Basic Outputs for _value transactions_, and Alias Outputs for storage of DID Documents. + +All outputs must hold a minimum amount of tokens to be stored on the ledger. For output types that can hold arbitrary data, for instance the Alias Output, the amount of tokens held by the output must cover the byte cost of the data stored. This prevents the ledger size from growing uncontrollably while guaranteeing that the data is not pruned from the nodes, which is important for resolving DID Documents. This deposit is fully refundable and can be reclaimed when the output is destroyed. + +Data stored in an output and covered by the storage deposit will be stored in _all_ nodes on the network and can be retrieved from any node. This provides strong guarantees for any data stored in the ledger. + +### Alias Output + +The [Alias Output](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: + +- **Amount**: the amount of IOTA coins held by the output. +- **Alias ID**: 32 byte array, a unique identifier of the alias, which is the BLAKE2b-256 hash + of the Output ID that created it. +- **State Index**: A counter that must increase by 1 every time the alias is state transitioned. +- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/main/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. +- **Unlock Conditions**: + - State Controller Address Unlock Condition + - Governor Address Unlock Condition + +Consuming an Alias Output in a transaction may transition it into the next state. The current state is defined as the consumed Alias Output, while the next state is defined as the **Alias Output with the same explicit `Alias ID` on the output side**. There are two types of transitions: `state transition` and `governance transition`. + +All outputs include an `Unlock Conditions` property. This feature defines how the output can be unlocked and spent. The Alias Output supports two types of unlock conditions that can be set: the state controller and governor. Each of these can be either an Ed25519 Address, Alias Address or an NFT Address. An Alias Output can have at most one of each unlock condition. + +The state controller can unlock a state transition. It is identified by an incremented `State Index` and can change the fields `Amount`, `State Index`, `State Metadata` among other properties. + +The governor, on the other hand, can unlock a governance transition indicated by an unchanged `State Index`. A governance transition can change the addresses of the state controller and governor. It also allows destroying the Alias Output. + +### Ledger and DID + +Storing DID Documents in the ledger state means they inherently benefit from the guarantees the ledger provides. + +1. Conflicts among nodes are resolved and dealt with by the ledger. +2. Replay attacks are mitigated since transactions need to be confirmed by the ledger. +3. Through the `State Index` a linear history for updates of a DID Document is provided. + +## DID Method Name + +The `method-name` to identify this DID method is: `iota`. + +A DID that uses this method MUST begin with the following prefix: `did:iota`. Following the generic DID specification, this string MUST be lowercase. + +## DID Format + +The DIDs that follow this method have the following ABNF syntax. It uses the syntax in [RFC5234](https://www.rfc-editor.org/rfc/rfc5234) and the corresponding definition for `digit`. + +``` +iota-did = "did:iota:" iota-specific-idstring +iota-specific-idstring = [ iota-network ":" ] iota-tag +iota-network = 1*6network-char +iota-tag = "0x" 64lowercase-hex +lowercase-hex = digit / "a" / "b" / "c" / "d" / "e" / "f" +network-char = %x61-7A / digit ; corresponds to the character range from "a" to "z" and "0" to "9". +``` + +It starts with the string "did:iota:", followed by an optional network name (1 to 6 lowercase alpha characters) and a colon, then the tag. +The tag starts with "0x" followed by a hex-encoded `Alias ID` with lower case a-f. + +### IOTA-Network + +The iota-network is an identifier of the network where the DID is stored. This network must be an IOTA Ledger, but can either be a public or private network, permissionless or permissioned. + +The following values are reserved and cannot reference other networks: + +1. `iota` references the main network which refers to the ledger known to host the IOTA cryptocurrency. +2. `atoi` references the development network of IOTA. +3. `smr` references the shimmer network. +4. `rms` references the development network of Shimmer. + +When no IOTA network is specified, it is assumed that the DID is located on the `iota` network. This means that the following DIDs will resolve to the same DID Document: + +``` +did:iota:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe +did:iota:0xe4edef97da1257e83cbeb49159cfdd2da6ac971ac447f233f8439cf29376ebfe +``` + +### IOTA-Tag + +An IOTA-tag is a hex-encoded `Alias ID`. The `Alias ID` itself is a unique identifier of the alias, which is the BLAKE2b-256 hash of the Output ID that created it. +This tag identifies the Alias Output where the DID Document is stored, and it will not be known before the generation of the DID since it will be assigned when the Alias Output is created. + +### Anatomy of the State Metadata + +In the `State Metadata` of the Alias Output must be a byte packed payload with header fields as follows: + +| Name | Type | Description | +| ------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Document Type | ByteArray[3] | Set to value **DID** to denote a DID Document. | +| Version | uint8 | Set value **1** to denote the version number of this method | +| Encoding | uint8 | Set to value to **0** to denote JSON encoding without compression. | +| Payload | (uint16)ByteArray | A DID Document and its metadata, where every occurrence of the DID in the document is replaced by `did:0:0`. It must be encoded according to `Encoding`. | + +The types are defined in [TIP-21](/tips/tips/TIP-0021/#data-types). + +#### Payload + +The payload must contain the following fields: + +- `meta`: contains metadata about the DID Document. For example, `created` to indicate the time of + creation, and `updated` to indicate the time of the last update to the document. It may also include other properties. +- `doc`: contains the DID Document. In the example below, the document only contains one verification method. The `id` and `controller` is specified by `did:0:0` which references the DID of the document itself, since the DID is unknown at the time of publishing. It also deduplicates the DID of the document to reduce the size of the state metadata, in turn reducing the required storage deposit. + +Example State Metadata Document: + +```json +{ + "doc": { + "id": "did:0:0", + "verificationMethod": [ + { + "id": "did:0:0#jkGOGVO3Te7ADpvlplr47eP9ucLt41zm", + "controller": "did:0:0", + "type": "JsonWebKey", + "publicKeyJwk": { + "kty": "OKP", + "alg": "EdDSA", + "kid": "jkGOGVO3Te7ADpvlplr47eP9ucLt41zm", + "crv": "Ed25519", + "x": "D5w8vG6tKEnpBAia5J4vNgLID8k0BspHz-cVMBCC3RQ" + } + } + ], + "authentication": ["did:0:0#jkGOGVO3Te7ADpvlplr47eP9ucLt41zm"] + }, + "meta": { + "created": "2023-08-28T14:49:37Z", + "updated": "2023-08-28T14:50:27Z" + } +} +``` + +## Controllers + +A state controller can directly update the DID Document and the amount of tokens held by the Alias Output, but it cannot destroy the output. A governor, on the other hand, can indirectly update the DID Document by updating the state controller. The governor can also destroy the output by performing a governance transition without producing an Alias Output with the same `Alias ID`. + +As of now, only one state controller and one governor can be set for an Alias Output. Support for multiple controllers may be possible depending on future updates of the protocol. + +## CRUD Operations + +Create, Read, Update and Delete (CRUD) operations that change the DID Documents are done through state or governance transitions of the Alias Output. + +**These operations require fund transfer to cover byte cost. Transactions must be carefully done in order to avoid fund loss.** For example, the amount of funds in the inputs should equal these in the outputs. Additionally, private keys of controllers must be stored securely. + +### Create + +In order to create a simple self controlled DID two things are required: + +1. An Ed25519 Address for which the private key is available, or control over an Alias or NFT Output. +2. A Basic, Alias or NFT Output with enough coins to cover the byte cost. + +Creation steps: + +1. Create the content of the DID Document like verification methods, services, etc. +2. Create the payload and the headers as described in the [Anatomy of the State Metadata](#anatomy-of-the-state-metadata). +3. Create a new Alias Output with the payload and the headers stored in its `State Metadata`. +4. Set the state controller and the governor unlock conditions to the addresses that should control state and governance transitions, respectively. +5. Set enough tokens in the output to cover the byte cost. +6. Publish a new transaction with an existing output that contains at least the storage deposit from step 6 as input, and the newly created Alias Output as output. + +Once the transaction is confirmed, the DID is published and can be formatted by using the `Alias ID` as the tag in [DID Format](#did-format). + +### Read + +The following steps can be used to read the latest DID Document associated with a DID. + +1. Obtain the `Alias ID` from the DID by extracting the `iota-tag` from the DID, see [DID Format](#did-format). +2. Obtain the network of the DID by extracting the `iota-network` from the DID, see [DID Format](#did-format). +3. Query the Alias Output corresponding to the `Alias ID` using a node running the [inx indexer](https://github.com/iotaledger/inx-indexer). Nodes usually include this indexer by default. +4. Assert that the extracted network matches the one returned from the node. Return an error otherwise. +5. Assert that the `Alias ID` of the returned output matches the `Alias ID` extracted from the DID. Return an error otherwise. +6. Retrieve the value of the `State Metadata` field from the returned output. +7. Validate the contents match the structure described in [Anatomy of the State Metadata](#anatomy-of-the-state-metadata). Return an error otherwise. +8. Decode the DID Document from the `State Metadata`. +9. Replace the placeholder `did:0:0` with the DID given as input. + +### Update + +Updating a DID Document can be achieved by the state controller performing a state transition of the Alias Output with the updated content: + +1. Create a copy of the Alias Output with the `Alias ID` set explicitly. +2. Pack the updated DID Document, as described in the [Anatomy of the State Metadata](#anatomy-of-the-state-metadata), into the `State Metadata` of the output. +3. Increment the `State Index`. +4. Set the `amount` of coins sufficient to cover the byte cost. +5. Publish a new transaction that includes the current Alias Output as input (along with any required Basic Outputs to consume to cover the `amount`, if increased) and the updated one as output. If the state controller unlock of the Alias Output references other Alias or NFT Outputs, those outputs must be unlocked in the same transaction, recursively. + +### Delete + +#### Deactivate + +Temporarily deactivating a DID can be done by deleting the contents of the `State Meadata` in the Alias Output, setting it to an empty byte array, and publishing an [update](#update). + +Another option is to [update](#update) the DID Document and set the `deactivated` property in its `metadata` to true. In both cases, the deactivated DID Document will be marked as `deactivated` when resolved. + +#### Destroy + +In order to permanently destroy a DID, a new transaction can be published by the governor that consumes the Alias Output without having a corresponding Alias Output on the output side with the same explicit `Alias ID`. This results in destroying the Alias Output and the DID. + +Note that this operation irreversibly and irrecoverably deletes the DID. This is because the `Alias ID` from which an IOTA DID is derived (see [IOTA-Tag](#iota-tag)) is generated from the hash of the input transaction that created it, which cannot generally be replicated. + +## IOTA Identity standards + +The `did:iota` method is implemented in the [IOTA Identity framework](https://github.com/iotaledger/identity.rs). This framework supports a number of operations that are standardized, some are standardized across the SSI community, and some are the invention of the IOTA Foundation. + +### Revocation + +Revocation of verifiable credentials and signatures can be achieved using the [Revocation Bitmap 2022](./revocation-bitmap-2022.mdx) where issuers store a bitmap of indices in the DID Document. These indices correspond to verifiable credentials they have issued. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. + +### Standardized Services + +The IOTA Identity framework also standardized certain `services` that are embedded in the DID Document. It is RECOMMENDED to implement these when implementing the `did:iota` method. + +Currently standardized `services`: + +- [Revocation Bitmap Service](./revocation-bitmap-2022.mdx#revocation-bitmap-service) + +## Security Considerations + +The `did:iota` method is implemented on the [IOTA](https://iota.org), a public permissionless and feeless Distributed Ledger Technology (DLT), making it resistant against almost all censorship attack vectors. Up until the `Coordicide` update for the IOTA network, a dependency on the coordinator exists for resolving ordering conflicts. This has a minor censorship possibility, that, in the worst case, can prevent transactions from getting confirmed. + +### Private Key Management + +All private keys or seeds used for the `did:iota` method should be equally well protected by the users. Private keys of the state controller and the governor are especially important as they control how keys are added or removed, providing full control over the identity. The IOTA Identity framework utilizes the [Stronghold project](https://github.com/iotaledger/stronghold.rs), a secure software implementation isolating digital secrets from exposure to hacks or leaks. Developers may choose to add other ways to manage the private keys in a different manner. + +## Privacy Considerations + +### Personal Identifiable Information + +The public IOTA and Shimmer networks are immutable. This means that once something is included, it can never be completely removed. For example, destroying an Alias Output will remove it from the ledger state, but it can still be stored in permanodes or by any party that records historical ledger states. + +That directly conflicts with certain privacy laws such as GDPR, which have a 'right-to-be-forgotten' for Personal Identifiable Information (PII). As such, users should NEVER upload any PII, including inside DID Documents. While verifiable credentials can be made public, this should only be utilized by Identity for Organisations and Identity for Things. + +### Correlation Risks + +As with any DID method, identities can be linked if they are used too often and their usage somehow becomes public. See [DID Correlation Risks](https://www.w3.org/TR/did-core/#did-correlation-risks). Additionally, a DID can be correlated with funds if the Alias Output used to store the DID Document or any of its controllers is used for holding, transferring or controlling coins or NFTs. diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/overview.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/overview.mdx new file mode 100644 index 00000000000..8ffb0951bd7 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/specifications/overview.mdx @@ -0,0 +1,15 @@ +--- +title: Specifications Overview +sidebar_label: Overview +description: Provide overview of the specifications +image: /img/Identity_icon.png +keywords: + - specifications +--- + +While IOTA Identity implements many existing standards, it also adds some additional features we would like to standardize ourselves. This section covers these features and how they work in great detail. These are not light reads and can be skipped. + +The current specifications are: + +- [IOTA DID](iota-did-method-spec.mdx): The specification for the IOTA DID Method implemented on the _Tangle_. +- [Revocation Bitmap 2022](revocation-bitmap-2022.mdx): The specification for an on-Tangle credential revocation mechanism. diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx new file mode 100644 index 00000000000..e44aa2c11b0 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx @@ -0,0 +1,201 @@ +--- +title: Revocation Bitmap +sidebar_label: Revocation Bitmap +description: The specification for the embedded revocation bitmap. +image: /img/Identity_icon.png +keywords: + - DID + - specs + - specifications + - revocation + - bitmap +--- + +# Revocation Bitmap 2022 + +## Abstract + +This specification describes a mechanism for publishing the revocation status of [verifiable credentials](../../explanations/verifiable-credentials.mdx) embedded in an issuer's DID document. + +## Introduction + +Revocation gives an issuer the capability to invalidate a credential they issued before its natural expiration date. To achieve this, issuers can embed an identifier in the `credentialStatus` field of a credential. Verifiers can then lookup that identifier in a separate list, to check whether the credential is still valid. This document specifies a mechanism of embedding such a list, in form of a bitmap, in the DID document of the issuer, where each bitmap index corresponds to a credential they have issued. This mechanism is space-efficient and enables a verifier to check a credential's status in a privacy-preserving manner and without requiring additional lookups or external resources. + +## Revocation Bitmap Concept + +The revocation status of a verifiable credential is expressed as a binary value. The issuer keeps a bitmap of indices corresponding to verifiable credentials they have issued. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. + +## Data Model + +### Revocation Bitmap Status + +For an issuer to enable verifiers to check the status of a verifiable credential, the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) property MUST be specified with the following properties: + +| Property | Description | +| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | The constraints on the `id` property are listed in the [Verifiable Credentials Data Model specification](https://www.w3.org/TR/vc-data-model/). The `id` MUST be a [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) that is the URL to a [Revocation Bitmap Service](#revocation-bitmap-service) in the DID Document of the issuer. It SHOULD include an `index` query set to the same value as `revocationBitmapIndex`, to uniquely identify the `credentialStatus`. If the `index` query is present, implementations SHOULD reject statuses where the `index` query's value does not match `revocationBitmapIndex`. | +| `type` | The `type` property MUST be `"RevocationBitmap2022"`. | +| `revocationBitmapIndex` | The `revocationBitmapIndex` property MUST be an unsigned, 32-bit integer expressed as a string. This is the index of the credential in the issuer's revocation bitmap. Each index SHOULD be unique among all credentials linking to the same [Revocation Bitmap Service](#revocation-bitmap-service). | + +#### Example + +An example of a verifiable credential with a `credentialStatus` of type `RevocationBitmap2022`. + +```json +{ + "@context": "https://www.w3.org/2018/credentials/v1", + "id": "https://example.edu/credentials/3732", + "type": ["VerifiableCredential", "UniversityDegreeCredential"], + "credentialSubject": { + "id": "did:iota:B8DucnzULJ9E8cmaReYoePU2b7UKE9WKxyEVov8tQA7H", + "GPA": "4.0", + "degree": "Bachelor of Science and Arts", + "name": "Alice" + }, + "issuer": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "issuanceDate": "2022-06-13T08:04:36Z", + "credentialStatus": { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw?index=5#revocation", + "type": "RevocationBitmap2022", + "revocationBitmapIndex": "5" + }, + "proof": { + "type": "JcsEd25519Signature2020", + "verificationMethod": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#key-1", + "signatureValue": "2eHdbDumMrer4pNVkaiYMqsVqVp2adq7bRcgTJZiw17Zeghk2ZT49YHwLwCCg35YKganBhxP6YSbzYoBK1AuCUv" + } +} +``` + +### Revocation Bitmap Service + +To allow verifiers to check the status of a [Revocation Bitmap Status](#revocation-bitmap-status), the DID document of the credential issuer MUST contain a [service](https://www.w3.org/TR/did-core/#services) with the following properties: + +| Property | Description | +| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | The constraints on the `id` property are listed in the [DID Core service specification](https://www.w3.org/TR/did-core/#services). The `id` property MUST be a DID URL uniquely identifying the revocation bitmap. | +| `type` | The `type` property MUST be `"RevocationBitmap2022"`. | +| `serviceEndpoint` | The `serviceEndpoint` MUST be generated according to the [service endpoint generation algorithm](#service-endpoint-generation-algorithm). | + +#### Example + +An example of an issuer's DID document where credential `"5"` in the `#revocation` service is revoked: + +```json +{ + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "verificationMethod": [ + { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#key-1", + "controller": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "z3hgM9fNkhwgT5mECbj1HdKoFNZgpffwQYEV8WBVHphXq" + } + ], + "capabilityInvocation": [ + { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#sign-0", + "controller": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", + "type": "Ed25519VerificationKey2018", + "publicKeyMultibase": "z83F6zbD3KqaxvQhqo25LvSXzoDdpZmp3EpPVonSVACwZ" + } + ], + "service": [ + { + "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", + "type": "RevocationBitmap2022", + "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" + } + ] +} +``` + +## Algorithms + +The following algorithms define how to generate, expand and validate revocation bitmaps. + +### Service Endpoint Generation Algorithm + +The following process MUST be followed when producing a `RevocationBitmap2022` to embed in a service endpoint: + +1. Let **bitmap** be a [_roaring bitmap_](https://roaringbitmap.org/) where each bit is initialized to 0. +2. For each revoked credential with an **index** not exceeding an unsigned, 32-bit integer, set the corresponding bit in **bitmap** at **index** to 1. +3. Generate the **bitmap serialization** according to the [roaring bitmap serialization format](https://github.com/RoaringBitmap/RoaringFormatSpec/) using the **bitmap** as input. +4. Generate a **compressed bitmap** by using the ZLIB compression algorithm [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] on the **bitmap serialization** and base64-encoding [[RFC4648](https://datatracker.ietf.org/doc/html/rfc4648)] the result. +5. Create the **service endpoint** by embedding the **compressed bitmap** in a data URL [[RFC2397](https://datatracker.ietf.org/doc/html/rfc2397)]. On the data url, the `` MUST be `application/octet-stream` and the `base64` attribute MUST be set. +6. Return the **service endpoint**. + +### Service Endpoint Expansion Algorithm + +The following process MUST be followed when expanding the endpoint from a service of type `RevocationBitmap2022`: + +1. Let **service endpoint** be a data url generated using the [service endpoint generation algorithm](#service-endpoint-generation-algorithm). +2. The `` of the **service endpoint** MUST be `application/octet-stream` and the `base64` attribute MUST be set, return an error otherwise. Let **compressed bitmap** be the `` part of the data url. +3. Generate an **uncompressed bitmap** by base64-decoding [[RFC4648](https://datatracker.ietf.org/doc/html/rfc4648)] the **compressed bitmap** and then decompressing the result using ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)]. +4. Generate the **bitmap** by deserializing the **uncompressed bitmap** according to the [roaring bitmap serialization format](https://github.com/RoaringBitmap/RoaringFormatSpec/). +5. Return the **bitmap**. + +### Validation Algorithm + +The following steps MUST be followed when checking whether a verifiable credential is revoked: + +1. Let **credential** be a verifiable credential containing a `credentialStatus` whose `type` is `RevocationBitmap2022`. +2. Let **revocation bitmap URL** be the `id` field of the **credential**'s `credentialStatus`. +3. Resolve the **revocation bitmap URL** to a **revocation bitmap service** in the issuer's DID document, and verify that the service `type` is `RevocationBitmap2022`. Return an error otherwise. +4. Expand the endpoint of the **revocation bitmap service** into a **revocation bitmap** according to the [service endpoint expansion algorithm](#service-endpoint-expansion-algorithm). +5. Let **revocation index** be the integer value of the `revocationBitmapIndex` property contained in the `credentialStatus` of the **credential**. +6. Let **revoked** be the value of the bit at index **revocation index** in the **revocation bitmap**. +7. Return `true` if **revoked** is 1, `false` otherwise. + +## Test Vectors + +This section provides test vectors to validate implementations against. + +### Test Vector 1 + +The following data URL decodes to a bitmap of length 0 where no index is revoked: + +`"data:application/octet-stream;base64,ZUp5ek1tQUFBd0FES0FCcg=="` + +### Test Vector 2 + +The following data URL decodes to a bitmap of length 3 where indices `5`, `398`, and `67000` are revoked: + +`"data:application/octet-stream;base64,ZUp5ek1tQmdZR0lBQVVZZ1pHQ1FBR0laSUdabDZHUGN3UW9BRXVvQjlB"`. + +### Test Vector 3 + +The following data URL decodes to a bitmap of length 16384 where all indices are revoked: + +`"data:application/octet-stream;base64,ZUp6dHhERVJBQ0FNQkxESEFWS1lXZkN2Q3E0MmFESmtyMlNrM0ROckFLQ2RBQUFBQUFBQTMzbGhHZm9q"` + +## Rationale + +This section describes the rationale behind some of the design decisions of this specification. + +### Compression and maximum size + +Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/main/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. +The precise size of a serialized bitmap varies based on the number and distribution of revoked indices. When indices are revoked uniformly randomly, roughly 100,000 - 200,000 can be achieved in a DID Document with compression, and significantly more if consecutive indices are revoked. + +ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] was chosen for having a free and open source software licence and being one of the most widely used compression schemes, which enhances the accessibility of this specification. Some other assessed algorithms produced only marginally better compression ratios but had far fewer existing implementations across different programming languages. + +### Compressed Bitstring vs. Roaring Bitmap + +Because of its space efficiency, a roaring bitmap is preferred for representing a bitmap in-memory. To avoid the dependency on roaring bitmap, we considered using a compressed bitstring as the serialization format. However, serialization of such a bitstring was 2-3x slower compared to roaring's serialization format, which becomes an issue on resource-constrained devices (e.g. smartphones) or in web browsers. + +### Comparison to `RevocationList2020` and `StatusList2021` + +The [RevocationList2020 specification](https://w3c-ccg.github.io/vc-status-rl-2020/) and [StatusList2021 specification](https://w3c-ccg.github.io/vc-status-list-2021/) both describe a similar revocation mechanism using a verifiable credential that contains a bitmap, similar to the `RevocationBitmap2022` approach. The credential is hosted outside of the DID document and the verifier thus needs to fetch it from an external resource, likely one controlled by the issuer. This has privacy implications as the issuer can track where a fetch request for the credential came from and potentially infer who the credential was verified by and for what purpose. The issuer can also potentially infer which credential was checked. Because `RevocationBitmap2022` is embedded in the issuer's DID document, which can be obtained without the their knowledge, this approach does not suffer from these privacy shortcomings. See also the [privacy considerations](#privacy-considerations). + +A downside of embedding the revocation list in the DID document is that storage in a distributed ledger (DLT) is usually more expensive than other storage hosting solutions. The DLT might also impose message size limitations, capping the total number of revocations that can be done (see also [compression](#compression)). + +Another difference is that `RevocationList2020` specifies a minimum initial size of 131,072 for its bitstring, to mitigate the potential for correlating individuals when few credentials have been issued. `RevocationBitmap2022` uses a roaring bitmap instead of a bitstring, so the maximum size is not fixed (apart from the upper bound of an unsigned 32-bit integer). This means the bitmap cannot be used to correlate small populations without more information not present in the bitmap itself. However, both schemes still reveal publicly how many credentials have been revoked, which could be used to infer other information if more knowledge about how an issuer assigns credential revocation indexes is known. + +`StatusList2021` allows for explicitly stating the purpose of the list, currently either _revocation_ or _suspension_. This specification does not mandate that revoked credentials cannot be unrevoked, which means a `RevocationBitmap2022` can effectively also be used as a suspension list. + +### Privacy Considerations + +Because the revocation bitmap is embedded in the DID document, and thus available without contacting the issuer directly, the issuer cannot correlate how a holder uses their credential. + +An observer finding a service of type `RevocationBitmap2022` in a DID document can infer that this DID belongs to an issuer. However, DIDs of issuers tend to be publicly known, in contrast to DIDs of other entities, so this is unlikely to present an issue. External observers can monitor the frequency of revocations and potentially the total number of issued credentials, depending on how the issuer assigns credential indices (e.g. starting from 0 and incrementing the index for each issued credential). diff --git a/docs/build/identity.rs/1.1/docs/welcome.mdx b/docs/build/identity.rs/1.1/docs/welcome.mdx new file mode 100644 index 00000000000..c34a7f161ce --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/welcome.mdx @@ -0,0 +1,91 @@ +--- +description: The most important concepts that developers will need to know to utilize IOTA Identity to its full potential. +image: /img/Identity_icon.png +keywords: + - Identity + - guide + - TOC + - overview + - reference +--- +# IOTA Identity Framework + +![IOTA Identity](/img/banner/banner_identity.svg) + +The IOTA Identity framework implements the most common standards and patterns for Decentralized Identity in both a DLT agnostic and `iota` method specific manner. +It is designed to work for Identity for [People](#identity-for-people), [Organizations](#identity-for-organizations), +[Things, and Objects](#identity-for-things) acting as a unifying-layer of trust between everyone and everything. + +## Introduction to Decentralized Identity + +Decentralized or Self-Sovereign Identity (SSI) gives individuals full control over their online identity, +offering a remedy for database breaches, lack of digital trust, and stringent privacy laws like GDPR. +Digital identity bridges the gap between online pseudonyms and real-world personas, enabling true verifiable identities. This gives individuals the power to choose which data to share and with whom. + + + +### Identity for People + +:::info Privacy + +IOTA Identity builds a new internet, without usernames, passwords, endless repeated forums, or uncontrolled data harvesting. + +::: + +Information about anyone's life is spread across many locations. Most people have numerous unorganized important documents at home, hundreds of online accounts, and many more online footprints. Through statistical predictive analysis, computer programs can harvest unverified online information sources and create a reasonably accurate profile about our lives. These profiles are accurate enough for targeted advertising and personalized content but lack the proof and trust for them to be used in business. This results in an antiquated customer experience where we have to submit our age and address for every purchase we make and every account we create. It also inhibits our ability to do many online tasks like requesting and extending licenses or taking out a mortgage. + +Self-Sovereign Identity is about returning autonomy and privacy to the individual, while also improving our online experience. Some movements focus on data privacy, preventing companies from using our information altogether, but with the IOTA Identity framework you control which part of the information you want to reveal. The user can create a single online profile containing all our personal information. They can decide who they share what information with, and a verifier checks if the information is correct, making the data trustworthy. This moves their online profile from a statistical estimation by corporate entities to an accurate and verifiable profile under their own control. + +IOTA Identity allows a new internet without usernames, passwords, endless repeated forms, or data harvesting. Users have ultimate control and can choose to supply service providers with their personal data, who in return provide personalized experiences. Data will still flow, and perhaps even more than before, but it will always be in the interest of the individual, instead of a corporation. People will gain additional benefits in sharing their data, either in monetary value or improved customer experience. This sort of system is not possible in a non-neutral environment such as permissioned or fee-based ledgers. + +Governmental mechanisms for building _digital identities_ are currently being established throughout Europe and Asia, with demand increasing around the globe. However, they are managed by single entities and restricted to the governments that created them. By decentralizing a framework for these standards to adapt to, we have a system for intergovernmental verification of individuals and devices. A person’s digital identification will be transferable across borders like a passport. However, it will no longer require the trust of the issuing government due to the digital trust established by the open and auditable system. + +### Identity for Organizations + +:::info GDPR + +IOTA Identity allows organizations to comply with GDPR in a cost-efficient and privacy-enabling manner + +::: + +Corporations are associated with greed and abuse of power. This reputation stems from the role some have chosen to take within society. Corporations are trusted with our data, but often do not act responsibly; vulnerability, fix, patch, repeat. In software and systems, we have seen this cycle repeat. Headlines on data leaks are now an ever-present feature in the news. + +IOTA Identity presents an opportunity for companies to embrace a new role in the ecosystem. Traditional approaches do not provide cost-efficient solutions to new legislation like GDPR. IOTA Identity enables organizations to change their processes to comply with the new regulations in a cost-efficient and privacy-enabling manner. Features of “Data Protection and Privacy by Design” shift responsibility over Personal Identifiable Information (PII) from organization to customer, and organizations no longer need to store that data. The relationship between customer and organization is also tightened as communication via a third party Identity provider like Google or Facebook is no longer needed. + +Due to Know-Your-Customer (KYC) and Anti-Money Laundering (AML) obligations, companies can be certain who their customers are. These services also provide unique insight into the state of their customers’ data. These insights can be combined and translated into verifiable credentials, providing a new “Trust Anchor” service with a potential for new business models. KYC and AML credentials would return the autonomy of personal data back to the customer. Once companies accept the KYC and AML credentials of other companies, the enrollment time for new customers is significantly reduced, as are the costs. With the personal data secured by the customer, companies can afford to store less data in their own databases, reducing risk and responsibility and fulfilling the goals of legislation such as GDPR. + +Organizations that have their own decentralized identities can also combat fraud and increase control over their online brand. Companies can sign invoices and agreements using their decentralized identities. While interacting with the customers, they will also be able to reliably identify themselves. + +### Identity for Things + +:::info TRUST + +IOTA Identity adds the missing key ingredient for the "Economy of Things": Trust. + +::: + +With Identity of Things (IDoT), devices are provided with a unique global identity that are able to prove many attributes including their capabilities, specifications, and authenticity. People, organizations, and other devices will only pay devices that can prove their ability to fulfill the required task. This basis of trust prevents fraudulent activity. Additonally, by using the IOTA ledger, the progress of the task can be immutably logged. With the combination of the IOTA protocol and the IOTA Identity framework, we can automate the entire interaction between all parties, without requiring predefined trust. The [Industry Marketplace](https://industry.iota.org/) provides a perfect example of how this framework and level of autonomy work. + +There is a growth in applications that generate Digital Twins for physical devices or objects, such as the Asset Administration Shell (AAS) developed for our Industry Marketplace. Digital twins are online profiles representing a device or object. They provide a virtual state that mirrors reality by emulating the device or object’s physical state through data input sources like sensors. A digital twin is often used to monitor states and execute actions based on the information. Digital twins are only rarely shared outside the associated application and organization due to the complexities in sharing and matching profiles. However, empowered with a digital identity, digital twin sharing would become possible. Once data is verifiable and trusted, digital twins can form the basis for the digital representation of physical devices and objects. This allows other identities to interact with them automatically and provide services such as predictive maintenance. + +Security is a major barrier in advancing technologies that use IoT. Whether it is the smart devices in our own homes, or at a larger scale, the critical infrastructure of organizations and cities, security must be at the core. It is central to any globally-unifying identity solution. By integrating advanced research in cryptography and digital ledgers, and combining it with a scalable access and management system, security will become a core functionality of the systems we build. By using scalable device DIDs, integrating verification and reputation schemes, and allowing for transparent tamper-proof accountability, we begin to understand how we can future-proof the security of our systems, allowing us to start trusting the process, and not the patch. + +### One Framework. Any Identity + +The IOTA Identity framework serves as a ubiquitous layer of trust for the internet. Whether it's people, organizations, or things, the framework enables the creation of digital identities, fosters trust-building through verifiable credentials, and ensures seamless interaction among different entities. + +### Why IOTA? + +IOTA stands apart as a scalable, feeless Distributed Ledger Technology (DLT), suitable for a universal identity solution. Some features of IOTA include: + +* **Cost-effectiveness**: Usually, minting decentralized identities costs fees. IOTA Identity has redeemable and predictable deposits but no fees. +* **High availability**: Identities are always available on all network nodes - for holders, issuers, and verifiers. +* **Security**: Write access to identities is secured through multi-level control structures with key rotation capabilities, allowing for backup access and recoverability. +* **Integrity**: Updates go through the same mechanisms that secure the IOTA network, guaranteeing consistent state and history of all identities. diff --git a/docs/build/identity.rs/1.1/docs/workflow.mdx b/docs/build/identity.rs/1.1/docs/workflow.mdx new file mode 100644 index 00000000000..1952b19f7ad --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/workflow.mdx @@ -0,0 +1,179 @@ +--- +title: Identity.rs workflow +sidebar_label: Workflow +description: Learn about the software development process of the IOTA Identity repository. +image: /img/Identity_icon.png +keywords: + - Workflow + - Contribute + - GitHub + - explanation +--- + +# Identity Workflow + +In this article you will learn about the software development process for the IOTA Identity repository as well as key terms, functions, and the overall operability of the workflow components. + +## Issues + +Issues are opened when a certain task or problem is noted but cannot immediately be fixed. Issues may contain bug reports, requests, or larger topics. Please use the correct GitHub issue template for your issue type. Only IOTA Foundation members should use the task templates flagged for maintainers. You should make sure to [label](#issue-labels) the issue correctly. As a contributor, you may also add issues to a certain [project](https://github.com/iotaledger/identity.rs/projects/). + +## Git + +### Pull Requests + +New branches should be pushed to the GitHub repository as soon as possible, making them public to all contributors. In addition, a pull request (PR) should be opened in draft status, describing the goals and any requirements of the changes. To generate good [changelogs](#changelog), a PR title must be written in a way that is suitable as a changelog entry while the PR must be [labeled](#pr-labels) correctly. + +Any code written should frequently be committed and pushed back to the GitHub branch. This acts as both a back-up mechanism and provides transparency towards other contributors and the community. You should also pull from the origin branch of the PR regularly to prevent merge conflicts. + +Other contributors are encouraged to provide feedback on a PR during its development. A PR should be flagged as 'ready for review' once the PR has implemented all changes and no further commits are planned by the main contributors. The repository requires a review to be provided by at least one (other) developer in the team that works in the same language or has knowledge of the work before it can be merged. For larger PRs, the review of two maintainers is recommended. + +Once a PR is approved, the preferred method is "squash-and-merge" for non-epic branches to keep the destination branch clean and allow for many small commits while work is in-progress. Epic branches must instead be merged with the merge commits of included PRs intact, so the [changelog generator](#changelog) can detect included changes. Once merged in, the source branch may be deleted. + +### Branches + +IOTA Identity always has two permanent branches: `main` and `dev`. Both branches are protected and disallow direct commits; the only changes allowed are from pull requests approved and merged by maintainers. + +#### [Main](https://github.com/iotaledger/identity.rs/tree/main) (main) + +The `main` branch contains a stable version of the code that is released towards package managers such as `crates.io` and `npm`. This branch only accepts PRs that merge from `release` or `hotfix` branches. + +#### [Dev](https://github.com/iotaledger/identity.rs) (dev) + +The `dev` branch contains a frequently updated version of the code that is released towards package managers under a development flag. These releases may contain breaking changes without a strong notice towards developers using them. While the `dev` branch may get frequent updates, it may not contain unfinished features. Any large, multi-PR feature should be committed to a long-lived `epic` branch created specifically for that feature. + +### Work Branches + +These are branches that developers work on directly. Their names should be prefixed appropriately with one of the following categories. For example, a PR fixing a null pointer bug in the Wasm bindings might be created from a branch called `fix/client-non-null`. + +#### Feature (feat/, doc/, chore/, fix/) + +Singular PR contributions should create either a `feat`, `doc`, `chore`, or `fix` branch, depending on the type of changes. These may be branched from either the `dev` branch or an `epic` branch. If the number of lines of code are going to be relatively small and the work completed in a single PR, the branch should be created from `dev` and merged back into `dev` once completed. Otherwise, the branches should be created from their associated `epic` branch and be merged back into the same `epic` branch. + +- `feat` branches should contain changes to the code that expand or modify functionality. They should also include updates to the documentation and examples related to the feature, though `doc` branches may be used to catch up on documenting a feature. +- `doc` branches contain changes to code documentation or the wiki. These PRs should be kept relatively small to avoid burdening a reviewer with too many documentation updates at once. For example, during a documentation catch-up, we will have a branch or PR per documentation page. +- `chore` branches are short-lived branches that contain no significant features or functionality changes, but rather smaller fixes such as typos, code fixes, minor refactors, and CI changes. +- `fix` branches correct bugs such as compilation errors or where existing features do not behave as expected, generally without introducing any new functionality or breaking changes. + +We recommend integrating `dev` or `epic` regularly, depending on where the branch started, to reduce the possibility and potential size of merge conflicts. + +#### Epic (epic/) + +Long-lived `epic` branches should be created as soon as a feature is expected to require more than one PR. The `epic` branch should be branched from `dev` and should only accept merges that are related to the feature being developed. A PR should be opened as soon as the branch is created to publicly notify contributors about the development, the goals and requirements of the feature, and the existence of the branch. It is recommended you integrate `dev` often to reduce the possibility and potential size of merge conflicts. Epic branches must not be squash-merged, otherwise the [changelog generator](#changelog) will not detect its constituent PRs. + +### Semantic Versioning + +Semantic Versioning (SemVer) describes a methodology for versioning of software to convey meaning and guarantees through the version string. A typical version string looks like `2.3.1`, where `2` is called the major version, `3` the minor version and `1` the patch or bugfix version. + +The central idea is that every part of the version string conveys meaning. A major change introduces behavior that is incompatible with previous versions of the software, while a minor change adds backwards-compatible functionality and a patch simply fixes a problem. So just by looking at the version string, an implementer will understand the effort needed to integrate a new version. + +For more detailed information and an overview of advanced features, see [Semantic Versioning 2.0.0](https://semver.org/). Though this is not to be confused with [Sentimental Versioning](http://sentimentalversioning.org/). + +### Changelog + +A changelog is a file describing a software project for humans to grasp the type and content of changes from version to version. Changelogs are closely related to the versioning of software, since individual changes are grouped into versions that are, in our case, referenced by a [SemVer string](#semantic-versioning). We generally follow the recommendations from [keepachangelog](https://keepachangelog.com/en/1.0.0/). The changelog in this project is generated from the titles and [labels](#pr-labels) of [pull requests](#pull-requests). + +#### PR labels + +Labels are used to categorize changes in [pull requests](#pull-requests). Adding a label will include the labeled [PR](#pull-requests) title in the related section of the generated [changelog](#changelog). + +Changelogs are generated for the core Rust library and each binding separately. To attach a PR to a specific changelog, use the following labels: + +##### `Rust` + +This includes the PR in the core Rust library changelog. + +##### `Wasm` + +This includes the PR in the WASM bindings changelog. + +It is also necessary to add an appropriate label for the type of change in the PR. The following labels determine in which section a PR title will appear: + +##### Changed + +Maps to the major version of [Semantic Versioning](#semantic-versioning). +labels: `Breaking change` + +##### Added + +Maps to the minor version of [Semantic Versioning](#semantic-versioning). +labels: `Added` + +##### Patch + +Maps to the patch version of [Semantic Versioning](#semantic-versioning). +labels: `Patch` + +##### Deprecated + +Marks features that will be removed in the feature. No special version consideration should apply here, since the feature did not change yet. +labels: `Deprecated` + +##### Removed + +Marks features as being removed. Typically the features should have been deprecated in the previous version. This maps to the major version of [Semantic Versioning](#semantic-versioning). +labels: `Removed` + +##### Excluded tags + +Marks changes that should not be part of the changelog. This should only be used for documentation and rare exceptions. +labels: `Documentation`, `No changelog` + +Please note that a PR can only be listed in one section of a changelog. So attaching the labels `Rust` `Added` `Patch` to a PR, for example, is invalid because `Added` and `Patch` conflict. + +##### Release summary + +To attach a release summary to a version in the changelog, an issue with the label `release-summary` must be created. Create a GitHub milestone matching the version you want to describe and attach it to the issue. The issue can be closed immediately. The text of the issue will be included in the changelog as the release summary. + +### Issue Labels + +The following labels are used to categorize issues but do not have any effect on changelogs: `Request`, `Enhancement`, `Bug`, `Chore`, `Dependencies`, `Help wanted`, `Duplicate`, `Wontfix`. + +## Release + +With the release process, we can deliver versions of our software to the community. We use sensible automation where it helps to remove tedium. However, some steps that require active decision-making remain manual. + +The final list of changes from the [changelog](#changelog) informs the version of the release. If at least one change mapping to a major version is included, the major version needs to be incremented. In that case, the minor and patch versions are set to `0`. If there are no changes related to a major version, but changes related to a minor version are present, the minor version needs to be incremented while the patch version is set to `0`. Otherwise, only the patch version is incremented. Determining the version of the release is the responsibility of the person performing the release. + +The determined version of the release is used to create the [hotfix](#hotfix) or [release](#release) branch. For example, a major release from the previous version `v2.3.1` will create the `release/v3.0.0` branch. + +Notice the `v` in front of the version. We [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) all release in git in the form of `vMAJOR.MINOR.PATCH`. For bindings, we prefix the tag with the binding name, so a tag for Wasm would look like `wasm-v1.2.3`. Bindings and the core Rust library are versioned and released independently. + +Additionally, we may release `dev` versions separately for both bindings and the core Rust library. These releases are meant as a preview of upcoming versions. For example, if the current version is `1.2.3` with the tag `v1.2.3`, we may release `v1.3.0-dev.1` which is then superseded by the actual `1.3.0` release. + +You should follow these steps to create a release: + +1. Ensure all the changes you want to release are on the `dev` branch. +2. Select the appropriate GitHub Actions workflow, e.g. `Rust Create Release PR`. + 2.1. Decide if you want to create a `dev` or `main` release. + 2.2. Determine the next version string. + 2.3. Run the workflow. The workflow will create a PR from `dev` targeting `dev` with release related changes. +3. Review the PR. + 3.1. The PR will update the changelog, check that it has all expected entries in the appropriate sections and the determined version matches the changelog according to [SemVer](#semantic-versioning). + 3.2. The PR will update project version strings, ensure these are correct and match the expected version. + 3.3. Refer to [Troubleshooting](#troubleshooting) if anything is incorrect. +4. Merge the PR. + 4.1. On merging to `dev`, an automatic workflow is triggered that builds and publishes artifacts to the appropriate package manager (`crates.io` for Rust, `npm` for the WASM bindings), and creates a GitHub Release (only for `main` version releases of the core Rust library). +5. For `main` version releases, merge the `dev` branch into the `main` branch. + +### Troubleshooting + +#### The changelog entries have the wrong description in the release PR + +Update the titles of the relevant PRs, then re-run the workflow with the same parameters. The release PR will be updated with the new changelog. + +#### The changelog in the release PR is missing entries, has unrelated entries, or entries in the wrong section + +Fix the [labels](#pr-labels) on the relevant PRs, then re-run the workflow with the same parameters. The release PR will be updated with the new changelog. + +#### The release description in the release PR is missing or wrong + +Fix the issue description, milestone, and label according to the [release summaries guide](#release-summary) and re-run the workflow with the same parameters. The release PR will be updated with the new changelog. + +#### Features or code are missing from the release + +Merge the code into the `dev` branch, then re-run the workflow with the same parameters. The release PR will be updated with the changes. + +#### I want to abort the release for any reason + +Close the PR. You can reopen it later. // TODO: can I just re-run the workflow? Maybe that needs an "I want to resume an aborted release" section? diff --git a/docs/build/identity.rs/1.1/sidebars.js b/docs/build/identity.rs/1.1/sidebars.js new file mode 100644 index 00000000000..242088be3b6 --- /dev/null +++ b/docs/build/identity.rs/1.1/sidebars.js @@ -0,0 +1,113 @@ +/** + * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of that group + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + + Create as many sidebars as you want. + */ + +module.exports = { + // By default, Docusaurus generates a sidebar from the docs folder structure + // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], + + // But you can create a sidebar manually + + docs: [ + { + type: 'doc', + id: 'welcome', + label: 'Welcome', + }, + { + type: 'category', + label: 'Getting Started', + collapsed: false, + items: ['getting-started/rust', 'getting-started/wasm'], + }, + { + type: 'category', + label: 'Explanations', + items: [ + 'explanations/decentralized-identifiers', + 'explanations/verifiable-credentials', + 'explanations/verifiable-presentations', + 'explanations/about-alias-outputs', + ], + }, + { + type: 'category', + label: 'How To', + items: [ + { + type: 'category', + label: 'Decentralized Identifiers (DID)', + items: [ + 'how-tos/decentralized-identifiers/create', + 'how-tos/decentralized-identifiers/update', + 'how-tos/decentralized-identifiers/resolve', + 'how-tos/decentralized-identifiers/delete', + ], + }, + { + type: 'category', + label: 'Verifiable Credentials', + items: [ + 'how-tos/verifiable-credentials/create', + 'how-tos/verifiable-credentials/revocation', + ], + }, + { + type: 'category', + label: 'Verifiable Presentations', + items: ['how-tos/verifiable-presentations/create-and-validate'], + }, + { + type: 'category', + label: 'Domain Linkage', + items: ['how-tos/domain-linkage/create-and-verify'], + }, + 'how-tos/key-storage', + ], + }, + { + type: 'category', + label: 'References', + collapsed: true, + items: [ + { + type: 'category', + label: 'API', + items: [ + { + type: 'doc', + id: 'references/api/wasm', + label: 'Wasm', + }, + { + type: 'link', + label: 'Rust', + href: 'https://docs.rs/identity_iota/latest/identity_iota/index.html', + }, + ], + }, + { + type: 'category', + label: 'Specifications', + items: [ + 'references/specifications/overview', + 'references/specifications/iota-did-method-spec', + 'references/specifications/revocation-bitmap-2022', + ], + }, + ], + }, + 'glossary', + 'contribute', + 'workflow', + 'contact', + 'faq', + ], +}; diff --git a/versionedConfig.js b/versionedConfig.js index a2300a3e37d..cf2c3b8e3b5 100644 --- a/versionedConfig.js +++ b/versionedConfig.js @@ -68,6 +68,10 @@ exports.buildPluginsConfig = [ icon: 'Identity', subsection: 'build-layer-1', versions: [ + { + label: '1.1', + badges: ['IOTA', 'Shimmer'], + }, { label: '1.0', badges: ['IOTA', 'Shimmer'], From 5ee5e44cae9cd9f042cb386e5cdec16b7abf41f2 Mon Sep 17 00:00:00 2001 From: Abdulrahim Al Methiab Date: Mon, 22 Jan 2024 14:41:27 +0100 Subject: [PATCH 02/19] add SD JWT page --- .../selective-disclosure.mdx | 126 ++++++++++++++++++ docs/build/identity.rs/1.1/sidebars.js | 1 + 2 files changed, 127 insertions(+) create mode 100644 docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx new file mode 100644 index 00000000000..ed9c7189348 --- /dev/null +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx @@ -0,0 +1,126 @@ +--- +sidebar_label: Selective Disclosure +description: Explain VC with selective disclosure. +image: /img/Identity_icon.png +keywords: + - verifiable + - credentials + - SD-JWT + - Disclosure +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Selective Disclosure (SD-JWT) + + +Holders of verifiable credentials may prefer not to disclose all the information contained within it to the verifier. Instead, they may opt to share only a specific subset of the properties included in the VC. The identity library implements the [IETF Specifications](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html) which outlines a mechanism to enable the selective disclosure of individual properties within the JSON object of JWT claims. + +## Concept + +#### Issuance ✍️ +During the issuance process, the issuer replaces a subset of the JWT claims with digests of their salted values and signs the JWT. Next, the signed JWT alongside with the plain text disclosures and the salt used the for digest creation are sent to the holder. + +#### Presentation 📃 +At this stage, the holder has the flexibility to selectively choose which values to disclose to the verifier. The chosen values are sent in plain text with the JWT that contains the digests to the verifier. + +:::note +Only values replaced by digests through the issuer can be selectively disclosed. The holder **can not** conceal values provided in plain text in the JWT claims. +::: + + +#### Validation 🔬 +With these values and a valid signature, the verifier is able to reconstruct a verified VC that exclusively contains the information the holder intended to disclose. + +## How it works + +As the SD JWT remains a valid JWT, giving the following JWT claim of an address credential in accordance with the [VC Data Model v1.1](https://www.w3.org/TR/vc-data-model/#json-web-token): + + +```json +{ + "iss": "did:iota:tst:0x899d07a766f93c2af1a19a3f4583ad338fc94c5d84b6afcadf49b197e1cb693e", + "jti": "https://example.com/credentials/3732", + "nbf": 1705925652, + "sub": "did:iota:tst:0x6c045e1f658197b432cfc7c66350b8781dca50f820e9de0fcdf0029b4b384355", + "vc": { + "@context": "https://www.w3.org/2018/credentials/v1", + "credentialSubject": { + "address": { + "country": "DE", + "locality": "Maxstadt", + "postal_code": "12344", + "street_address": "Weidenstraße 22" + }, + "name": "Alice" + }, + "type": [ + "VerifiableCredential", + "AddressCredential" + ] + } +} + +``` + +The issuer makes the values of "locality", "postal_code", "street_address" selectively disclosable, giving the holder the freedom to select what details of the address to be disclosed and presented. + +```json +{ + "_sd_alg": "sha-256", + "iss": "did:iota:tst:0x899d07a766f93c2af1a19a3f4583ad338fc94c5d84b6afcadf49b197e1cb693e", + "jti": "https://example.com/credentials/3732", + "nbf": 1705925652, + "sub": "did:iota:tst:0x6c045e1f658197b432cfc7c66350b8781dca50f820e9de0fcdf0029b4b384355", + "vc": { + "@context": "https://www.w3.org/2018/credentials/v1", + "credentialSubject": { + "address": { + "_sd": [ + "8Dai0-GMZgkzmdryGzjYufUaRFkiNWzVsJJdWucwu84", + "jemTNaG_wiHauwmwWiWREsirAlr91qugPds4MA8e2xo", + "iakC9Dfe2r9fGnOaAr_pGg1b7CwITBjcwE7-O7WlMnY" + ], + "country": "DE" + }, + "name": "Alice" + }, + "type": [ + "VerifiableCredential", + "AddressCredential" + ] + } +} +``` + +:::note +The digests are included in the `_sd` property in `address`. This allows both keys and values to be concealed. +::: + +For further details, see the [Example](#full-example-code) below and the [sd-jwt-payload crate](https://github.com/iotaledger/sd-jwt-payload). + + +## Key Binding JWT + +When a verifier receives an SD-JWT, it could be important to verify if the identity of the presenter matches the holder of the Credential. For that a Key binding JWT can be used, in which the holder can verify the possession of the private key that corresponds with his public key. + + +## Full Example Code + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/7_sd_jwt.rs +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/6_sd_jwt.ts +``` + + + diff --git a/docs/build/identity.rs/1.1/sidebars.js b/docs/build/identity.rs/1.1/sidebars.js index 242088be3b6..30f4668b4d5 100644 --- a/docs/build/identity.rs/1.1/sidebars.js +++ b/docs/build/identity.rs/1.1/sidebars.js @@ -57,6 +57,7 @@ module.exports = { items: [ 'how-tos/verifiable-credentials/create', 'how-tos/verifiable-credentials/revocation', + 'how-tos/verifiable-credentials/selective-disclosure', ], }, { From 558d711932734139da4371f9fa4625e632ef62b9 Mon Sep 17 00:00:00 2001 From: Abdulrahim Al Methiab Date: Tue, 23 Jan 2024 00:38:39 +0100 Subject: [PATCH 03/19] fix outdated docs --- .../explanations/verifiable-presentations.mdx | 17 +++-- .../how-tos/verifiable-credentials/create.mdx | 27 ++------ .../create-and-validate.mdx | 62 +++---------------- .../explanations/verifiable-presentations.mdx | 17 +++-- .../how-tos/verifiable-credentials/create.mdx | 27 ++------ .../create-and-validate.mdx | 62 +++---------------- 6 files changed, 38 insertions(+), 174 deletions(-) diff --git a/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx b/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx index 096ec3734ff..77efe77d1fa 100644 --- a/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx +++ b/docs/build/identity.rs/1.0/docs/explanations/verifiable-presentations.mdx @@ -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. \ No newline at end of file +per `JwtPresentationOptions`. However, verifiers and different implementations could choose to ignore that property, +so setting a signature expiration alone should not be relied upon. diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx index 4d3ba898da4..d38cad99f94 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx @@ -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 @@ -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 @@ -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 diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx index 7ae2620df99..b1a8cdc47b3 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -13,8 +13,8 @@ import TabItem from '@theme/TabItem'; The IOTA Identity Framework enables holders tos easily construct [verifiable presentations](./../../explanations/verifiable-presentations.mdx). -As demonstrated in the [example](#example), -holders only need to pass in their credentials to present and sign the presentation. +As demonstrated in the [example](#example-code), +holders only need to pass in their credentials to create a JWT presentation. ## Properties @@ -34,49 +34,27 @@ However, the holder property should be included to satisfy [subject-holder relat After creation, the holder signs the verifiable presentation using a private key linked to one of the verification methods in their DID Document and transmits it to a verifier for validation. -## Proof Options +## Creation and Validation -A digital signature on a verifiable presentation provides data integrity, +Verifiable presentation can be issued as a JWT that provides data integrity, and also proves the [DID](../../explanations/decentralized-identifiers.mdx) of the holder. -### Metadata Properties - -The proof section embedded in a presentation 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 presentation was signed. -- **Expires**: Timestamp after which the presentation is no longer considered valid. -- **Challenge**: Arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request. -- **Domain**: Arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge. -- **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. - :::note -Verifiers should always send a challenge and domain +Verifiers should always send a challenge to [mitigate replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations). - ::: -A verifier could also choose to ignore some or all of these options. -See [Proof Verifier Options](#proof-verifier-options) for more information. - -## Validation The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. -See the [example](#example) for a demonstration of how to validate a presentation. +See the [example](#example-code) for a demonstration of how to validate a presentation. The framework checks: - **Semantic structure**: Ensures the presentation and its credentials adhere to the specification. - **Presentation proof**: Verifies the presentation signature against the DID Document of the holder. - **Credential proofs**: Verifies the credential signatures against the DID Documents of their respective issuers. -- **Optional validations**: Additional checks on signatures and credential fields can be configured by the verifier. -Note that a verifier may specify which DID Documents to use for the holder and issuers. -Otherwise, they are resolved from the Tangle automatically. Currently, the following are **not** checked automatically: @@ -91,25 +69,6 @@ against the given options. The default validation behavior may be modified by the following options. -### Proof Verifier Options - -While the framework always verifies that the digital signature on a verifiable presentation is valid, -a verifier may validate additional fields in the proof on a presentation. -Notably, to mitigate potential [replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations), -a verifier should always check that the challenge and domain fields match what was sent to the holder when -requesting the presentation. - -The following options are available: - -- **Method Scope**: check the signing verification method has a particular [verification relationship](https://www.w3.org/TR/did-core/#verification-relationships). Overridden by the proof purpose check. -- **Method Type**: check the signing verification method has a particular type. -- **Challenge**: check the challenge field matches this string. -- **Domain**: check the domain field matches this string. -- **Proof Purpose**: require a specific purpose on the proof. See [Proof Options](#proof-options). -- **Allow Expired**: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs. - -See [Proof Options](#proof-options) for more information on setting these properties as a holder when signing a verifiable presentation. - ## Subject-Holder Relationship Specifies the expected relationship between the holder that signed the verifiable presentation and the subject @@ -117,7 +76,7 @@ specified in each [verifiable credential](./../../explanations/verifiable-creden This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. -By default, the framework always enforces that the holder matches the subject on all credentials. +By default, the framework always enforces that the holder matches the subject. The following options are available to modify that behavior: @@ -132,13 +91,6 @@ for further discussion on the different subject-holder relationships. ::: -### Credential Validation Options - -These options specify conditions that all credentials in a verifiable presentation must satisfy. - -- **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 the [`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**: See [Proof Verifier Options](#proof-verifier-options) for details. ## Example Code diff --git a/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx b/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx index 096ec3734ff..77efe77d1fa 100644 --- a/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx +++ b/docs/build/identity.rs/1.1/docs/explanations/verifiable-presentations.mdx @@ -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. \ No newline at end of file +per `JwtPresentationOptions`. However, verifiers and different implementations could choose to ignore that property, +so setting a signature expiration alone should not be relied upon. diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx index 4d3ba898da4..d38cad99f94 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx @@ -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 @@ -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 @@ -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 diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx index 7ae2620df99..b1a8cdc47b3 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -13,8 +13,8 @@ import TabItem from '@theme/TabItem'; The IOTA Identity Framework enables holders tos easily construct [verifiable presentations](./../../explanations/verifiable-presentations.mdx). -As demonstrated in the [example](#example), -holders only need to pass in their credentials to present and sign the presentation. +As demonstrated in the [example](#example-code), +holders only need to pass in their credentials to create a JWT presentation. ## Properties @@ -34,49 +34,27 @@ However, the holder property should be included to satisfy [subject-holder relat After creation, the holder signs the verifiable presentation using a private key linked to one of the verification methods in their DID Document and transmits it to a verifier for validation. -## Proof Options +## Creation and Validation -A digital signature on a verifiable presentation provides data integrity, +Verifiable presentation can be issued as a JWT that provides data integrity, and also proves the [DID](../../explanations/decentralized-identifiers.mdx) of the holder. -### Metadata Properties - -The proof section embedded in a presentation 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 presentation was signed. -- **Expires**: Timestamp after which the presentation is no longer considered valid. -- **Challenge**: Arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request. -- **Domain**: Arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge. -- **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. - :::note -Verifiers should always send a challenge and domain +Verifiers should always send a challenge to [mitigate replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations). - ::: -A verifier could also choose to ignore some or all of these options. -See [Proof Verifier Options](#proof-verifier-options) for more information. - -## Validation The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. -See the [example](#example) for a demonstration of how to validate a presentation. +See the [example](#example-code) for a demonstration of how to validate a presentation. The framework checks: - **Semantic structure**: Ensures the presentation and its credentials adhere to the specification. - **Presentation proof**: Verifies the presentation signature against the DID Document of the holder. - **Credential proofs**: Verifies the credential signatures against the DID Documents of their respective issuers. -- **Optional validations**: Additional checks on signatures and credential fields can be configured by the verifier. -Note that a verifier may specify which DID Documents to use for the holder and issuers. -Otherwise, they are resolved from the Tangle automatically. Currently, the following are **not** checked automatically: @@ -91,25 +69,6 @@ against the given options. The default validation behavior may be modified by the following options. -### Proof Verifier Options - -While the framework always verifies that the digital signature on a verifiable presentation is valid, -a verifier may validate additional fields in the proof on a presentation. -Notably, to mitigate potential [replay attacks](./../../explanations/verifiable-presentations.mdx#security-considerations), -a verifier should always check that the challenge and domain fields match what was sent to the holder when -requesting the presentation. - -The following options are available: - -- **Method Scope**: check the signing verification method has a particular [verification relationship](https://www.w3.org/TR/did-core/#verification-relationships). Overridden by the proof purpose check. -- **Method Type**: check the signing verification method has a particular type. -- **Challenge**: check the challenge field matches this string. -- **Domain**: check the domain field matches this string. -- **Proof Purpose**: require a specific purpose on the proof. See [Proof Options](#proof-options). -- **Allow Expired**: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs. - -See [Proof Options](#proof-options) for more information on setting these properties as a holder when signing a verifiable presentation. - ## Subject-Holder Relationship Specifies the expected relationship between the holder that signed the verifiable presentation and the subject @@ -117,7 +76,7 @@ specified in each [verifiable credential](./../../explanations/verifiable-creden This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. -By default, the framework always enforces that the holder matches the subject on all credentials. +By default, the framework always enforces that the holder matches the subject. The following options are available to modify that behavior: @@ -132,13 +91,6 @@ for further discussion on the different subject-holder relationships. ::: -### Credential Validation Options - -These options specify conditions that all credentials in a verifiable presentation must satisfy. - -- **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 the [`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**: See [Proof Verifier Options](#proof-verifier-options) for details. ## Example Code From baa390157784575aff65eca7ef3a1f8686d0ea9e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eike=20Ha=C3=9F?= Date: Tue, 23 Jan 2024 16:07:03 +0100 Subject: [PATCH 04/19] remove identity 0.6 version --- banners/identity-06-deprecation-migration.mdx | 3 - banners/identity-deprecated.mdx | 1 - .../docs/concepts/advanced/did_messages.mdx | 34 - .../0.6/docs/concepts/advanced/overview.mdx | 11 - .../concepts/advanced/storage_interface.mdx | 130 - .../decentralized_identifiers/create.mdx | 52 - .../decentralized_identifiers/overview.mdx | 77 - .../private_tangle.mdx | 41 - .../decentralized_identifiers/resolve.mdx | 192 - .../decentralized_identifiers/update.mdx | 421 -- .../verifiable_credentials/create.mdx | 99 - .../verifiable_credentials/overview.mdx | 48 - .../verifiable_credentials/revocation.mdx | 72 - .../verifiable_presentations.mdx | 184 - docs/build/identity.rs/0.6/docs/contact.mdx | 17 - .../build/identity.rs/0.6/docs/contribute.mdx | 49 - .../0.6/docs/decentralized_identity.mdx | 113 - docs/build/identity.rs/0.6/docs/faq.mdx | 53 - .../getting_started/create_and_publish.mdx | 62 - .../0.6/docs/getting_started/install.mdx | 73 - .../0.6/docs/getting_started/overview.mdx | 40 - docs/build/identity.rs/0.6/docs/glossary.mdx | 140 - .../identity.rs/0.6/docs/introduction.mdx | 76 - .../0.6/docs/libraries/overview.mdx | 14 - .../docs/libraries/rust/getting_started.mdx | 68 - .../0.6/docs/libraries/wasm/api_reference.mdx | 5937 ----------------- .../docs/libraries/wasm/getting_started.mdx | 219 - .../docs/specs/did/iota_did_method_spec.mdx | 375 -- .../0.6/docs/specs/did/overview.mdx | 11 - .../0.6/docs/specs/didcomm/CHANGELOG.md | 36 - .../0.6/docs/specs/didcomm/overview.mdx | 83 - .../didcomm/protocols/authentication.mdx | 219 - .../specs/didcomm/protocols/connection.mdx | 256 - .../docs/specs/didcomm/protocols/issuance.mdx | 448 -- .../0.6/docs/specs/didcomm/protocols/post.mdx | 115 - .../specs/didcomm/protocols/presentation.mdx | 388 -- .../didcomm/protocols/revocation-options.mdx | 118 - .../specs/didcomm/protocols/revocation.mdx | 289 - .../docs/specs/didcomm/protocols/signing.mdx | 216 - .../specs/didcomm/protocols/termination.mdx | 85 - .../didcomm/resources/credential-info.mdx | 66 - .../didcomm/resources/problem-reports.mdx | 64 - .../identity.rs/0.6/docs/specs/overview.mdx | 16 - .../0.6/docs/specs/revocation_bitmap_2022.mdx | 201 - .../0.6/docs/tutorials/migrate-stronghold.mdx | 181 - .../0.6/docs/tutorials/overview.mdx | 14 - .../tutorials/validate_university_degree.mdx | 224 - docs/build/identity.rs/0.6/docs/workflow.mdx | 179 - docs/build/identity.rs/0.6/sidebars.js | 153 - versionedConfig.js | 8 - 50 files changed, 11971 deletions(-) delete mode 100644 banners/identity-06-deprecation-migration.mdx delete mode 100644 banners/identity-deprecated.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/advanced/did_messages.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/advanced/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/advanced/storage_interface.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/create.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/private_tangle.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/resolve.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/update.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/create.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/revocation.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/verifiable_presentations.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/contact.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/contribute.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/decentralized_identity.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/faq.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/getting_started/create_and_publish.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/getting_started/install.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/getting_started/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/glossary.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/introduction.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/libraries/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/libraries/rust/getting_started.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/libraries/wasm/api_reference.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/did/iota_did_method_spec.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/did/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/CHANGELOG.md delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/authentication.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/connection.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/issuance.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/post.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/presentation.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation-options.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/signing.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/termination.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/resources/credential-info.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/didcomm/resources/problem-reports.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/specs/revocation_bitmap_2022.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/tutorials/migrate-stronghold.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/tutorials/overview.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx delete mode 100644 docs/build/identity.rs/0.6/docs/workflow.mdx delete mode 100644 docs/build/identity.rs/0.6/sidebars.js diff --git a/banners/identity-06-deprecation-migration.mdx b/banners/identity-06-deprecation-migration.mdx deleted file mode 100644 index b88a03ffb94..00000000000 --- a/banners/identity-06-deprecation-migration.mdx +++ /dev/null @@ -1,3 +0,0 @@ -This version of IOTA Identity is the last version targeting Chrysalis networks and is deprecated. Please upgrade to the latest version of [IOTA Identity for Stardust Networks](/identity.rs/0.7/introduction/). - -Also, with Identity Rust 0.6.3 and Wasm 0.6.1 a breaking change was introduced that requires a migration of existing Stronghold Snapshot files. You can find migration instructions [here](/identity.rs/0.6/tutorials/migrate-stronghold/). diff --git a/banners/identity-deprecated.mdx b/banners/identity-deprecated.mdx deleted file mode 100644 index 271441c16e4..00000000000 --- a/banners/identity-deprecated.mdx +++ /dev/null @@ -1 +0,0 @@ -This version of IOTA Identity is deprecated. Please upgrade to [Identity 0.6 for Chrysalis Networks](/identity.rs/welcome/) and follow the migration instructions for upgrading Stronghold Snapshot files [here](/identity.rs/tutorials/migrate-stronghold/), or upgrade to the latest version of [IOTA Identity for Stardust Networks](/identity.rs/0.7/introduction/). diff --git a/docs/build/identity.rs/0.6/docs/concepts/advanced/did_messages.mdx b/docs/build/identity.rs/0.6/docs/concepts/advanced/did_messages.mdx deleted file mode 100644 index ea33b2df858..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/advanced/did_messages.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: DID Messages -sidebar_label: DID Messages -description: Learn how IOTA Identity recreates and validates the state from its origin to the current version using Integration and Differentiation Chains. -image: /img/Identity_icon.png -keywords: - - Diff Chain - - Differentiation Chain - - Integration Chain - - smart contracts - - Chronicle - - state - - stateless ---- - -TODO: Explain the concept of DID Messages and how they can be used to optimize DID updates. - -### Valid DID Documents - -Most DID methods are implemented on a Distributed Ledger Technology (_DLT_), such as Bitcoin, Ethereum or IOTA. Most common DID implementation on DLTs are based on fit-for-purpose Blockchains that store the state of a DID Document in the ledger, or a general purpose Blockchain that utilize smart contracts to store the state. Updating a DID Document where the state is understood by the network is straightforward. The network can determine if an action is legal and if a cryptographic signature is provided correctly, as it understands the underlying data structure, and can update the state accordingly. The individual state updates, or transactions, can be forgotten. - -The IOTA Tangle is unable to track, state, or understand the data structure. Storing the state is neither possible in the ledger, nor via a Smart contract (yet). Therefore, IOTA Identity has to recreate and validate the state from the origin of the Identity to the current version. The process involves querying all the relevant transactions from the Tangle, ordering them, filtering out the transactions that perform illegal actions or have an incorrect signature and then recreate state. As this requires the full history of the Identity, we recommend utilizing [Chronicle](https://github.com/iotaledger/chronicle.rs), an IOTA permanode, which stores the entire history of the Tangle. Further research will be performed to reduce storage requirements for IOTA Identity based applications. - -### DID Messages - -Due to this constant need for state recreating, unique performance improvements have been design and implemented for IOTA Identity. Most DID Documents will need few to no updates, however identities that sign a lot of Verifiable Credentials might update more frequently, as will be explained in the Verifiable Credentials section. To support higher frequency identity updates, we have introduced a unique solution called the “Integration Chain” and the “Differentiation Chain” (Diff Chain). - -The Integration Chain is a chain of transactions that contain full DID Documents. They are unrestricted in what they can add or remove from the DID Document. Every Integration Chain transaction points to a separate new Diff Chain. These Diff Chain transactions only list the changes to a DID Document and are therefore more compact. It is, however, restricted in rotating the signing key, making it fast and easy to validate the transaction. - -Once a new Integration chain transaction is created, it will take all Diff Chain updates and compress them into a new DID Document, essentially combining them all into a single transaction. This reduces the amount of updates that need to be queried and validated tremendously. For example, lets assume every Diff chain contains 100 updates. Then validating a DID that has done 1050 updates, only requires the validation of 10 Integration Chain updates and 40 Diff Chain updates (The latest Diff Chain). We skipped out on 10 Diff Chains each containing 100 updates, and only validated the 10 Integration Chain updates and the last Diff Chain containing 40 updates. If we estimate every update to be on average 1 Kb, we only have to download 50 kb of information and validate it, which is significantly less than the otherwise 1.025 Mb of information. - -The improved performance and ability to handle frequently updated DID Documents is especially beneficial for Verifiable Credential Revocation. - -TODO: mention future revocation scheme replacement for MerkleKeyCollection. diff --git a/docs/build/identity.rs/0.6/docs/concepts/advanced/overview.mdx b/docs/build/identity.rs/0.6/docs/concepts/advanced/overview.mdx deleted file mode 100644 index 07e07a204ba..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/advanced/overview.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Advanced Concepts Overview -sidebar_label: Overview -description: Provide overview of the advanced concepts -image: /img/Identity_icon.png -keywords: - - advanced - - concepts ---- - -TODO: Provide overview of the advanced concepts diff --git a/docs/build/identity.rs/0.6/docs/concepts/advanced/storage_interface.mdx b/docs/build/identity.rs/0.6/docs/concepts/advanced/storage_interface.mdx deleted file mode 100644 index 725635ff466..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/advanced/storage_interface.mdx +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Storage Interface -sidebar_label: Storage Interface -description: Explain the need for the storage interface and how it can be implemented -image: /img/Identity_icon.png -keywords: - - storage - - storage interface - - storage adapter - - account - - signing - - encryption ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Introduction - -The high-level account API takes care of publishing updates to an identity and storing secrets securely. It does the latter by using an implementation of the `Storage` interface. In this section, we will go into more depth of the interface, and how to implement that interface. - -The key idea behind the interface is strongly inspired by the architecture of key management systems (KMS) or secure enclaves: once private keys are entered into the system, they can never be retrieved again. Instead, all operations using the key will have to go through that system. This approach is what allows `Storage` implementations to be architected more securely than simply storing and loading private keys from a regular database. Of course, the security is directly dependent on the concrete implementation, which is why we provide one such implementation using [Stronghold](https://github.com/iotaledger/stronghold.rs/), and strongly recommend using it. However, there are cases where one cannot use `Stronghold` or may want to integrate key management of identities into their own KMS or similar, which is why the `Storage` interface is an abstraction over such systems. Any implementation of that interface can then be used by the `Account`. - -The storage interface has three major categories of functions. A brief overview of those functions: - -- DID Operations: Management of identities. - - `did_create`: Based on a private key, or a generated one, creates a new DID. - - `did_list`: List all DIDs in this `Storage`. - - `did_exists`: Returns whether the given DID exists in this `Storage`. - - `did_purge`: Wipes all data related to the given DID. -- Key Operations: Various functionality to managing cryptographic keys. - - `key_generate`: Generates a new key for the given DID. - - `key_insert`: Inserts a pre-existing private key for the given DID `location`. - - `key_public`: Calculates and returns the public key for the given location to a private key. - - `key_delete`: Removes the key at the given location. - - `key_sign`: Signs the given data with the key at the given location. - - `key_exists`: Returns whether the key at the given location exists. -- Data Operations: Used for keeping state persistent. Storages only need to serialize and store the data. - - `chain_state_get`: Returns the `ChainState` data structure for the given `DID`. - - `chain_state_set`: Sets the `ChainState` data structure for the given `DID`. - - `document_get`: Returns the DID document for the given `DID`. - - `document_set`: Sets the DID document for the given `DID`. - -## Storage Layout - -### Identifiers - -There are two types of identifiers in the interface, DIDs and key locations. A DID identifies an identity, while a key location identifies a key. An implementation recommendation is to use the DID as a partition key. Everything related to a DID can be stored in a partition identified by that DID. Importantly, the location of a key is only guaranteed to be unique within the DID partition it belongs to. If no partitioning is used, then DID and key location should be combined (e.g. concatenated) to produce a single, globally unique (i.e. across all identities) identifier for a key in storage. - -### Representations - -A `KeyLocation` is a compound identifier based on the fragment of a verification method and the hash of a public key. The motivation for this design is that a `KeyLocation` can be derived given a DID document and one of its verification methods. Thus, no additional state is necessary. - -Canonical string representations of the `IotaDID` and `KeyLocation` type can be obtained using the string representation of a DID and the `canonical` method on `KeyLocation` respectively. These representations are intended to be kept stable as much as possible. - -### Example layout - -This illustrates the recommended approach for partitioning the storage layout (where `location -> key` is a mapping from `location` to `key`): - -- `did:iota:Ft3wA8Tv2nF25hij3aegR54Wvqju7t5zqW9xnCB5L3Wu` - - `sign-0:16843234495045965331 -> 0xc6f0dbacd56156ff4c383d549ac61ada87f8aa69454f3bfae99f5fa9e093a5c3` - - `kex-0:7560300328640998700 -> 0xe494e36164e0a760140f3a9ab7dfdad38edac698f93d5239655dbd7499194760` -- `did:iota:DSvXWs7FUch9MQcaUKmrRFZyHYcHwt3t3pbjvKsQBfep` - - `sign-0:16843234495045965331 -> 0xc6f0dbacd56156ff4c383d549ac61ada87f8aa69454f3bfae99f5fa9e093a5c3` - - `kex-0:16546298247591944074 -> 0x8e1d037cd343f84276ab737b638da9095bcb6052f7fd9628d21d20f434f9959a` - - `key:8559754420653090937 -> 0x4ef484a54aa16503878aa1ecaa6d73cb8254aefa3f80a569ed33ca685289d01e` - -Note how fragments (such as `kex-0`) can appear more than once, but the hash of the public key - calculated from the stored private key - makes the location unique in general. - -:::caution - -Although unlikely in practice, even the same private key can be used across different DIDs, which produces the same key location (here `sign-0:16843234495045965331`) and it's important that these are stored independently, so that deleting one does not accidentally delete the other. Hence why a key's full identifier in storage needs to be based on the DID _and_ the key location. - -::: - -That said, the following flattened structure also satisfies the requirements: - -- `did:iota:Ft3wA8Tv2nF25hij3aegR54Wvqju7t5zqW9xnCB5L3Wu:sign-0:16843234495045965331 -> 0xc6f0dbacd56156ff4c383d549ac61ada87f8aa69454f3bfae99f5fa9e093a5c3` -- `did:iota:Ft3wA8Tv2nF25hij3aegR54Wvqju7t5zqW9xnCB5L3Wu:kex-0:7560300328640998700 -> 0xe494e36164e0a760140f3a9ab7dfdad38edac698f93d5239655dbd7499194760` -- `did:iota:DSvXWs7FUch9MQcaUKmrRFZyHYcHwt3t3pbjvKsQBfep:sign-0:16843234495045965331 -> 0xc6f0dbacd56156ff4c383d549ac61ada87f8aa69454f3bfae99f5fa9e093a5c3` -- `did:iota:DSvXWs7FUch9MQcaUKmrRFZyHYcHwt3t3pbjvKsQBfep:kex-0:16546298247591944074 -> 0x8e1d037cd343f84276ab737b638da9095bcb6052f7fd9628d21d20f434f9959a` -- `did:iota:DSvXWs7FUch9MQcaUKmrRFZyHYcHwt3t3pbjvKsQBfep:key:8559754420653090937 -> 0x4ef484a54aa16503878aa1ecaa6d73cb8254aefa3f80a569ed33ca685289d01e` - -The primary advantage of the partitioning is that it simplifies the implementation of the `did_purge` operation, which wipes all data belonging to a given DID. With partitioning, this operation can simply wipe the partition whereas a storage with a flattened layout will have to do more work. - -## Indexing - -The interface has two methods called `did_list` and `did_exists`. These return the list of stored DIDs, and whether a DID exists in storage, respectively. Implementations are thus expected to maintain a list or index of stored DIDs. An identity created with `did_create` is added to the index, while an identity deleted through `did_purge` is removed from the index. - -If the storage implementation can be accessed concurrently, then access to the index needs to be synchronized, since it is unique per storage instance. - -## Implementation - -The IOTA Identity framework ships two implementations of `Storage`. The `MemStore` is an insecure in-memory implementation intended as an example implementation and for testing. The secure and recommended `Storage` is `Stronghold`. `Stronghold` may be interesting for implementers to look at, as it needs to deal with some challenges the in-memory version does not have. - -This section will detail some common challenges and embeds the `MemStore` implementations in Rust and TypeScript. - -### Challenges - -The `did_create` method takes the fragment of the initial verification method, the name of a network in which the DID will eventually exist, and an optional private key. From these inputs, it either generates a key or uses the passed private key to calculate the public key and from that derive the DID. In case a key needs to be generated, the challenge is to obtain the location for the key to be stored at. Since the key location depends on the public key, but key generation likely needs a location for the key to be stored at, there is a circular dependency that needs to be resolved. This can be resolved in at least two ways. - -1. Generate the key at a random location, then derive the actual location and move the key there -2. If moving a key is not possible, then an additional mapping from key location to some storage-internal location identifier can be maintained. Then it's possible to generate the key at some storage-internal location, calculate the key location and store the mapping. - -Since this also needs to happen before the DID can be derived from the public key, similar approaches can be used to work around the not-yet available DID partition key. Storages may choose to have one statically identified partition where keys are generated initially, and then moved from there. Storages whose restrictions do not allow for this, may want to use the flattened storage layout described in [example layout](#example-layout) and use the mapping approach. - -### Storage Test Suite - -The `StorageTestSuite` can be used to test the basic functionality of storage implementations. See its documentation ([Rust docs](https://docs.rs/identity_iota/0.6.1/identity_iota/account_storage/struct.StorageTestSuite.html), [Wasm docs](../../libraries/wasm/api_reference.mdx#StorageTestSuite)) for more details. - -### Examples - -This section shows the Rust and TypeScript `MemStore` implementations, which are thoroughly commented. - - - - -```ts reference -https://github.com/iotaledger/identity.rs/tree/support/v0.6/bindings/wasm/examples-account/src/custom_storage.ts -``` - - - - -```rust reference -https://github.com/iotaledger/identity.rs/tree/support/v0.6/identity_account_storage/src/storage/memstore.rs -``` - - - diff --git a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/create.mdx b/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/create.mdx deleted file mode 100644 index 5a9d22b9d2c..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/create.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: Creating a Decentralized Identity -sidebar_label: Create and Publish -description: Create DID Documents and publish them to the Tangle -image: /img/Identity_icon.png -keywords: - - Documents - - DID - - Tangle - - Create - - Publish ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -When someone or something wants to benefit from Self-Sovereign Identity, they must first create a Decentralized Identity. This identity consists of many parts that have different functions. This page will cover both the basics and the details about identity creation, storage, and publishing to the Tangle. - -The example below utilizes the high-level account module of the IOTA Identity framework to create an identity. The account is the easiest method of using IOTA Identity. It is recommended to use the account for your use cases, although a lower-level API is also available, providing more flexibility at the cost of more complexity. - -## Creating an Identity Using the Account - -:::tip Using Replit - -Select your programming language of choice and press the green play button to execute the example. - -::: - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/src/create_did.ts -``` - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/account/create_did.rs -``` - - - - -The first step in this example is the creation of an account. This acts as a stateful object that manages one or more identities. The account provides an interface to execute high-level operations on identities, such as creating, updating, and storing them. - -Next, the identity is created and published to the IOTA Tangle. This operation will generate a private key, storing it in the account, generating a DID, DID Document, and publishing it to the Tangle. Once it is uploaded to the Tangle, it becomes immutable, meaning that this version of the identity can never be altered or removed. The only way to update or delete an identity is by publishing a new version, which we will discuss in the next section. This immutability is what makes a Decentralized Identity solution based on Distributed Ledger Technology (DLT) trustworthy. The public keys inside the DID Document can never be changed without having access to the private key, allowing the users to completely control their own identities. The rest of the example shows how to retrieve (resolve) the identity from the Tangle and how it can be deleted. - -### Identity Generation Process - -The generation of an identity starts with a randomly generated asymmetric key pair. This can be generated by the IOTA Identity framework or can be provided as a parameter during the creation process. The public key is hashed using the `Blake2b-256` algorithm. This hash becomes the DID, creating a permanent and provable link between the initial keypair and the DID. The public key is then embedded into the initial DID Document and is used for verifying signatures created with the corresponding private key. This process can be observed and manipulated in depth by using the low-level API available for the IOTA Identity framework. These low-level APIs are available in [Rust](../../libraries/rust/getting_started.mdx#api-reference) and [WASM](../../libraries/wasm/api_reference.mdx) but are only recommended for complex use cases that require maximum flexibility in the framework. diff --git a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/overview.mdx b/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/overview.mdx deleted file mode 100644 index 8d5be2fc8b2..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/overview.mdx +++ /dev/null @@ -1,77 +0,0 @@ ---- -title: DID Introduction -sidebar_label: Introduction -description: The Decentralized Identifiers (DID) standard from W3C is the fundamental standard that supports the concept of a decentralized digital identity. Explore the basic aspects of the DID standard. -image: /img/Identity_icon.png -keywords: - - public keys - - Method Specification - - Decentralized Identifiers - - overview - - DLT ---- - -# Decentralized Identifiers (DID) - -The Decentralized Identifiers (DID) standard from the World Wide Web Consortium (W3C) is the fundamental standard that supports the concept of a decentralized digital identity. A DID is a unique identifier that contains information that can be resolved to a DID Document. This document contains data such as public keys, enabling the holder to prove ownership over their personal data, but also URIs that link to public information about the identity. This implementation complies to the [DID specifications v1.0 Working](https://www.w3.org/TR/did-core//). - -In the IOTA Identity framework, we have implemented the DID standard according to the `iota` [DID Method Specification](../../specs/did/iota_did_method_spec.mdx). We recommend seeing the `iota` DID Method Specification as the golden standard for DID on IOTA. Other implementations of DID on IOTA are recommended to follow the `iota` DID Method Specification. However, it is not necessary to implement a novel Method implementation for every project, so feel free to utilize this framework directly. - -An example of a DID conforming to the `iota` method specification: -`did:iota:8dQAzVbbf6FLW9ckwyCBnKmcMGcUV9LYJoXtgQkHcNQy` - -## Chapter Overview - -In this chapter, we will explain the basic aspects of the DID standard. We will explore the how and why of DID Documents and why IOTA is a very suitable technology to host the DID Documents and the rest of a Self-Sovereign Identity (SSI) Framework. - -## Decentralized Identifiers - -A Decentralized Identifier, or DID, is a unique identifier that is tied to a subject. This subject can be anything, like a person, an organization, an IoT device, or even an object. The identifier can be used by the subject to identify themselves through a digital format, providing a basis for online identification. The identifier looks like a set of random characters that includes some prefixes to determine which standard and implementation is used: - -`did:iota:8dQAzVbbf6FLW9ckwyCBnKmcMGcUV9LYJoXtgQkHcNQy` - -The World Wide Web Consortium (W3C) is a well-known standardization body that has standardized how DIDs should look and work. This provides a basis for different technologies that implement the DID standard to achieve _interoperability_. A full list of all implementations can be found [here.](https://www.w3.org/TR/did-spec-registries/#did-methods) Please keep in mind that unfortunately most of these methods are outdated and not maintained. - -## DID Documents - -The purpose of a DID is to help navigate to a DID Document, which is a document containing more information regarding the identity subject. This document contains data such as public keys, enabling the subject to prove ownership over their personal data, but also URIs that link to public information about the identity. - -The identifier contains all information to resolve a DID, providing the latest DID Document. The first three characters `did` indicate that the DID standard from W3C must be used to resolve the identifier. It is followed by a unique method name, in our case `iota`, to indicate that the IOTA method is used. The IOTA method is a specific implementation that follows the following [method spec](../../specs/did/iota_did_method_spec.mdx). This provides unique rules for the protocol to follow to result in the latest DID Document. In our case, it describes how DID Documents are uploaded and queried to and from the IOTA Tangle. Lastly, a DID contains a set of random characters that are unique per identity, this makes the identity unique and makes sure every identity resolves to a unique DID Document. - -:::tip Requires basic knowledge of Asymmetric Encryption - -The following and later sections require some basic knowledge of Asymmetric Encryption. Please read or view some materials on the subject before continuing. - -::: - -A DID Document mostly contains two important pieces of data: public keys and services. The public keys can be used to prove ownership over the identity, by cryptographically signing something with the associated private key. The public key can be used to verify that the identity subject signed the data and therefore controls the private key. Ownership over the private keys, therefore, proves ownership over the identity. This also means that it is very important to keep the private keys safe and secure. In addition, the public keys allow users to send encrypted data to the identity, using their public key, that only the identity owner can decrypt. - -:::caution - -Never share your private keys, seeds, passphrases with anyone. Not even IOTA Foundation members. This may lead to loss of IOTA funds or control over your own digital identity. - -::: - -Services are URIs that point to more information about the identity. This could be something as simple as a website for an organizational identity. These services are publicly available for all to read and should therefore not contain Personal Identifiable Information (PII) in the case of human identities. - -## Why use DIDs? - -DIDs allow any subject to have a unique identifier, that they can prove ownership of and at the same time provide a way to send them encrypted messages. The Identity is Self-Sovereign, meaning the subject is in control of when the identity is created but also destroyed. - -DIDs become more interesting in combination with Verifiable Credentials, which will be covered in a later section. In essence, Verifiable Credentials (VCs) are signed statements by trusted third parties about a certain identity. The signer, or Issuer, is referenced by the DID and so is the subject, often called the Holder. The Holder controls a copy of this statement and share it with other parties, the Verifiers, that can verify the statement and check which party made the statement, without having to ask the Issuer. Instead, they can verify the signature of the Issuer by checking the Issuers DID Document. This whole setup puts Holders back in control over their own data, but also makes the data much more trustworthy as it has become verifiable. - -## Why use IOTA Identity over other implementations? - -IOTA Identity is a framework to implement Self-Sovereign Identities on IOTA. Inherently, IOTA provides some unique features that have a major impact on the usability of the framework. - -### Feeless - -IOTA is a feeless Distributed Ledger Technology, which means that messages can immutably be stored inside the Tangle at no cost, nor a requirement of holding any _cryptocurrency_ tokens. That means that SSI applications can directly deploy towards the main network without any problems, as compared to most other SSI solutions running on a test network or having cryptocurrency requirements. This doesn't just make IOTA Identity have predictable costs and prevent issues around cryptocurrency holding taxes and legislation, it also makes it a fair network as anyone would be able to create one or more identities at no cost. The wealth of someone is irrelevant, making it the most inclusive SSI solution. - -### Ease-of-use - -Without the need for a token, IOTA Identity can directly be used on the main network without having to purchase and manage a cryptocurrency token. In addition, the framework provides easy-to-use APIs that allow both standardized behavior or flexible, yet more complex access. Lastly, IOTA Identity provides a [Stronghold](/stronghold.rs/welcome/ 'Stronghold is an open-source software library that was originally built to protect IOTA Seeds, but can be used to protect any digital secret.') solution for managing secrets securely, without requiring developers to reinvent the security wheel. - -### General Purpose DLT - -IOTA is a general-purpose DLT as compared to some for-purpose DLTs with restricted use cases. That means that SSI can easily be combined with other DLT features such as payments, data streams, smart contracts, and access control. It will no longer be needed to utilize multiple DLT projects alongside each other. diff --git a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/private_tangle.mdx b/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/private_tangle.mdx deleted file mode 100644 index d9ada7ec006..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/private_tangle.mdx +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: Create a DID on a Private Tangle -sidebar_label: Create a DID on a Private Tangle -description: Create a DID on a Private Tangle using the IOTA Identity Rust Library or its WASM bindings -image: /img/Identity_icon.png -keywords: - - Rust - - WASM ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Example - -This example shows how you can create a DID on a private tangle. You can run it together with a local [Hornet node](/hornet/welcome). - -### Account Module (Recommended) - -```rust reference -https://github.com/iotaledger/identity.rs/tree/support/v0.6/examples/account/config.rs -``` - -### Low-level API - - - - -```ts reference -https://github.com/iotaledger/identity.rs/tree/support/v0.6/bindings/wasm/examples/src/private_tangle.js -``` - - - - -```rust reference -https://github.com/iotaledger/identity.rs/tree/support/v0.6/examples/low-level-api/private_tangle.rs -``` - - - diff --git a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/resolve.mdx b/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/resolve.mdx deleted file mode 100644 index fe2809d8663..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/resolve.mdx +++ /dev/null @@ -1,192 +0,0 @@ ---- -title: Resolve an IOTA Identity -sidebar_label: Resolve -description: Explain how resolving works including arguments -image: /img/Identity_icon.png -keywords: - - Resolve ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -DID resolution is the process of fetching a [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) corresponding to a given [DID](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers). -The [IOTA Identity Framework](https://github.com/iotaledger/identity.rs) supports resolving DID Documents that are stored on an IOTA Tangle (public or private). The main tool supplied -by the IOTA Identity Framework to handle DID Document resolution in a type safe manner is the `Resolver`. A DID Resolver as defined in the [W3C Decentralized Identifiers specification](https://www.w3.org/TR/did-core/#dfn-did-resolvers) -enforces the signature of the resolution function in a manner that is more centered around Web/API resolution rather than a strongly typed framework. This is the reason why the `Resolver` provided by the IOTA Identity Framework deviates somewhat from -the W3C specification. - -## Resolving a DID from the main network - -The following example demonstrates how to resolve the DID: "did:iota:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV" from the `main` network. - - - - -```rust -use identity_iota::client::Resolver; -use identity_iota::iota_core::IotaDID; -use identity_iota::client::ResolvedIotaDocument; - -let resolver: Resolver = Resolver::new().await?; -let did: IotaDID = IotaDID::parse("did:iota:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV")?; - -let doc: ResolvedIotaDocument = resolver.resolve(&did).await?; - -``` - - - - -```js -const { DID, Resolver, ResolvedDocument } = require('@iota/identity-wasm/node'); - -const resolver = new Resolver(); -const did = DID.parse('did:iota:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV'); -const doc = await resolver.resolve(did); -``` - - - -What happens in this example can be explained on a high level as follows: The Resolver queries the Tangle for the history of the DID Document and utilizes it to recreate and validate the latest state of the DID Document. - -## Resolving from a private tangle - -Resolving a DID from a private tangle is similar to resolving a DID from the main net. The only difference is that -the resolver needs to be configured to have a client capable of operating on said private tangle. Building a `Client` configured for a specified Tangle is explained in [this example in Rust](https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/low-level-api/private_tangle.rs) and [this example in Javascript](https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples/src/private_tangle.js). - -The following example demonstrates how one can setup a `Resolver` with a given `client` and then attempt resolving a specified `did` which may be on any Tangle (public or private). - - - - -```rust -use identity_iota::client::Resolver; -use identity_iota::client::ResolverBuilder; -use identity_iota::iota_core::IotaDID; -use identity_iota::client::Client; -use identity_iota::client::Result; - - -async fn build_and_resolve(client: Client, did: IotaDID) -> Result { - let resolver_builder: ResolverBuilder = ResolverBuilder::new().await?; - let resolver: Resolver = resolver_builder.client(client).build().await?; - resolver.resolve(did).await -} -``` - - - - -```js -const { - DID, - Resolver, - ResolvedDocument, - Client, -} = require('@iota/identity-wasm/node'); - -async function buildAndResolve(client, did) { - const resolver = await Resolver.builder().client(client).build(); - const resolvedDocument = await resolver.resolve(did); - return resolvedDocument; -} -``` - - - - -In the example above the resolver will automatically try to resolve the DID from the network specified in the `did` (See [DID Format](../../specs/did/iota_did_method_spec.mdx#did-format)). -If the resolver was not built with a client configured for the given network name then an error will be thrown. Note that the `ResolverBuilder` can configure the `Resolver` to use -multiple networks as long as they have distinct valid names (max six characters). - -Note that in the context of an identity managed by an `Account` the DID document can also be resolved by simply calling the `resolve` method on the `Account` directly. - -## Resolution in the context of Verifiable Presentations - -As explained in [Verifiable Presentations](./../verifiable_credentials/verifiable_presentations.mdx) one resolves the DID Documents of the credential issuers and presentation holder -during verification of a verifiable presentation. Resolving the necessary DID Documents is done automatically when verifying presentations via the `Resolver`, but there are certain -advanced use cases where more control is desired. To accommodate for such situations the `Resolver` also comes equipped with additional stand alone methods that enable: - -- resolving a presentation holder's DID Document -- resolving all DID Documents of the distinct issuers of the credentials contained in the presentation -- resolving the issuer's DID Document for a given verifiable credential - -## Resolving the history of a DID Document - -The fact that a DID Document [can be updated](./update.mdx) implies that the state of the DID Document can change over time, or in other words the result of resolving a DID -also depends on when this operation was carried out. The `Resolver` provides a way to view the entire history of a DID Document (up to the time when the method is called). - - - - -```rust -use identity_iota::client::Resolver; -use identity_iota::iota_core::IotaDID; -use identity_iota::client::DocumentHistory; -use identity_iota::client::Result; - - -async fn call_resolve_history(did: IotaDID) -> Result { - let resolver: Resolver = Resolver::new().await?; - resolver.resolve_history(did).await? -} -``` - - - - -```js -const { DID, Resolver, DocumentHistory } = require('@iota/identity-wasm/node'); - -async function callResolveHistory(did) { - const resolver = new Resolver(); - const documentHistory = await resolver.resolveHistory(did); - return documentHistory; -} -``` - - - - -## Complete examples - -This section shows complete examples from the Iota Identity Framework code base. The first example creates a DID Document, publishes it to the Tangle and then resolves it. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/low-level-api/resolve_did.rs -``` - - - - -```js reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples/src/resolve_did.js -``` - - - - -This second example demonstrates creating, publishing changes and then resolving the history of a DID Document. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/tree/support/v0.6/examples/low-level-api/resolve_history.rs -``` - - - - -```js reference -https://github.com/iotaledger/identity.rs/tree/support/v0.6/bindings/wasm/examples/src/resolve_history.js -``` - - - - -Note that this example used the `Client` to resolve the history of the DID Document, but one could also use the `Resolver` for this task. diff --git a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/update.mdx b/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/update.mdx deleted file mode 100644 index 6557662c776..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/decentralized_identifiers/update.mdx +++ /dev/null @@ -1,421 +0,0 @@ ---- -title: Update DID Documents -sidebar_label: Update -description: How DID Documents can be manipulated and how updates should be published -image: /img/Identity_icon.png -keywords: - - Documents - - DID - - Tangle - - Update - - Publish ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -DID Documents can be extended by adding [Verification Methods](https://www.w3.org/TR/did-core/#verification-methods), [Services](https://www.w3.org/TR/did-core/#services) and custom properties. -A verification method adds public keys, which can be used to digitally sign things like a DID message or a verifiable credential, while a service can provide metadata around the identity via URIs. - -### Verification Methods - -As demonstrated by the [example](#example) below, the Iota identity framework offers easy-to-use methods for adding verification methods. - -The following properties can be specified for a verification method: - -- **id**: a [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for the verification method. It can be specified by setting the [fragment](https://www.w3.org/TR/did-core/#fragment); -- **type**: specifies the type of the Verification Method. The framework supports `Ed25519` and `X25519` key types. This property is automatically filled by the framework when specifying the verification material. -- **publicKeyMultibase**: multibase encoded public key which concludes the [verification material](https://www.w3.org/TR/did-core/#verification-material). This can be automatically generated by the framework or manually provided by users. - -### Verification Relationships - -[Verification relationships](https://www.w3.org/TR/did-core/#verification-relationships) express the relationship between the DID subject and the verification method. It can be used to specify the -the purpose of the verification method. - -The following relationships are supported by the Identity Framework: - -- **[Authentication](https://www.w3.org/TR/did-core/#authentication)**: used to specify authentication methods for the DID subject. -- **[Assertion](https://www.w3.org/TR/did-core/#assertion)**: can be used for verifiable credential verification. -- **[Key Agreement](https://www.w3.org/TR/did-core/#assertion)**: used for establishing secure communication channels. -- **[Capability Invocation](https://www.w3.org/TR/did-core/#capability-invocation)**: can be used to authorize updates to the DID Document. -- **[Capability Delegation](https://www.w3.org/TR/did-core/#capability-delegation)**: a mechanism to delegate cryptographic capability to another party. - -Verification methods can be either [embedded or referenced](https://www.w3.org/TR/did-core/#example-14-embedding-and-referencing-verification-methods). Referencing verification -methods allow them to be used by more than one verification relationship. -Upon creating a verification method using the identity framework, specifying the `MethodScope` option will result in an embedded verification method. Leaving that option unset will create the verification method as -a map entry of the `verificationMethod` property. Verification relationships can be added afterwards using references. - -:::warning - -Any update to the DID document must be signed using a verification method with `capability invocation` relationship to be valid. Removing all capability invocation verification methods -disallows any further updates to the document. - -::: - -### Services - -[Services](https://www.w3.org/TR/did-core/#services) allow adding other ways of communicating with the DID subject. An endpoint included in the DID Document can offer a way of reaching services for different purposes -like authentication, communicating, and discovery. - -The following properties can be specified for a service: - -- **id**: a [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) for referecing the service in the DID document. - It can be specified by setting the [fragment](https://www.w3.org/TR/did-core/#fragment). -- **type**: a string used to maximize interoperability between services. The framework does not perform any checks on the content of this string. -- **serviceEndpoint**: a URL that points to the service endpoint. - -## Example - -The following example demonstrates adding verification methods and services to a DID Document. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/account/manipulate_did.rs -``` - - - - -```js reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/src/manipulate_did.ts -``` - - - - -### Creating Identity - -The Example above starts by [creating an identity using the account](./create.mdx). - - - - -```rust -let mut account: Account = Account::builder() - .storage(stronghold) - .create_identity(IdentitySetup::default()) - .await?; -``` - - - - -```js -let builder = new AccountBuilder({ - storage, -}); -let account = await builder.createIdentity(); -``` - - - - -This will create a DID document and publish it to the tangle. - -```json -{ - "doc": { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "capabilityInvocation": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#sign-0", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z5k7vzMVuXXj8MJDcfzP2owvc8xKBA6BBsAkFf1GSNu2X" - } - ] - }, - "meta": { - "created": "2022-04-13T09:27:48Z", - "updated": "2022-04-13T09:27:48Z" - } -} -``` - -The created document only contains one verification method with [capabilityInvocation](https://www.w3.org/TR/did-core/#capability-invocation) relationship. -This method is used to sign the DID Document for publication to the Tangle. -The signature proves that the publisher of the document is in control over the capability invocation keys and is allowed to create, update or delete the DID Document. - -Any future updates to the DID Document in this example will be signed using this verification method. The Account will automatically sign each update with this method so individual -updates don't have to be explicitly signed. - -Furthermore, it's possible to rotate a capability Invocation key. In this case, the Account will sign next update with a key which was valid in the previous state of the DID Document. Afterwards it will -use the first (oldest) of the remaining capability invocation keys as a default signing method. -Other capability invocation keys can still be explicitly specified to sign an update. These can be set in `PublishOptions`. - -Note that the Account does not allow removing all capability invocation keys. - -### Adding Verification Methods - -Another verification method can be added to the DID document using the Account: - - - - -```rust -account - .update_identity() - .create_method() - .content(methodcontent::generateed25519) - .fragment("my-next-key") - .apply() - .await?; -``` - - - - -```js -await account.createMethod({ - content: MethodContent.GenerateEd25519(), - fragment: 'my-next-key', -}); -``` - - - - -The code above creates a new verification method that includes a newly generated Ed25519 public key, -signs the updated document using the private key of the default `capabilityInvocation` verification method -and publishes the document to the tangle. - -Since the `MethodScope` is not specified, the verification method will be created in the `verificationMethod` map. The updated DID Document will look as follows: - -```json -{ - "doc": { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "verificationMethod": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-next-key", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z2Zthec5siTfxCjPwZUHGDGybKNy9oc3ZYeftvEE2nEL3" - } - ], - "capabilityInvocation": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#sign-0", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z5k7vzMVuXXj8MJDcfzP2owvc8xKBA6BBsAkFf1GSNu2X" - } - ] - }, - "meta": { - "created": "2022-04-13T09:27:48Z", - "updated": "2022-04-13T09:28:06Z" - } -} -``` - -### Adding Verification Relationships - -Verification relationship can be attached to a verification method by referencing its fragment. - - - - -```rust -account - .update_identity() - .attach_method_relationship() - .fragment("my-next-key") - .relationships(vec![ - MethodRelationship::CapabilityDelegation, - MethodRelationship::CapabilityInvocation, - ]) - .apply() - .await?; -``` - - - - -```js -await account.attachMethodRelationships({ - fragment: 'my-next-key', - relationships: [ - MethodRelationship.CapabilityDelegation, - MethodRelationship.CapabilityInvocation, - ], -}); -``` - - - - -This will add `CapabilityDelegation` and `CapabilityInvocation` relationships to the created verification method with the fragment `my-next-key`. The `capabilityInvocation` -property now has both an embedded and a referenced verification method. - -```json -{ - "doc": { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "verificationMethod": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-next-key", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z2Zthec5siTfxCjPwZUHGDGybKNy9oc3ZYeftvEE2nEL3" - } - ], - "capabilityDelegation": [ - "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-next-key" - ], - "capabilityInvocation": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#sign-0", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z5k7vzMVuXXj8MJDcfzP2owvc8xKBA6BBsAkFf1GSNu2X" - }, - "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-next-key" - ] - }, - "meta": { - "created": "2022-04-13T09:27:48Z", - "updated": "2022-04-13T09:28:23Z" - } -} -``` - -### Adding a Service - -Similar to verification methods, services can be added to a DID Document. - - - - -```rust -account - .update_identity() - .create_service() - .fragment("my-service-1") - .type_("MyCustomService") - .endpoint(Url::parse("https://example.com")?) - .apply() - .await?; -``` - - - - -```js -await account.createService({ - fragment: 'my-service-1', - type: 'MyCustomService', - endpoint: 'https://example.com', -}); -``` - - - - -In JavaScript, the endpoint property type is a string, this must be a valid URL, otherwise an error will be thrown. -Additionally, custom properties can be added to a service by setting `properties` in both Rust and JavaScript. - -The updated Document with the newly created service looks as follows. - -```json -{ - "doc": { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "verificationMethod": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-next-key", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z2Zthec5siTfxCjPwZUHGDGybKNy9oc3ZYeftvEE2nEL3" - } - ], - "capabilityDelegation": [ - "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-next-key" - ], - "capabilityInvocation": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#sign-0", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z5k7vzMVuXXj8MJDcfzP2owvc8xKBA6BBsAkFf1GSNu2X" - }, - "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-next-key" - ], - "service": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-service-1", - "type": "MyCustomService", - "serviceEndpoint": "https://example.com/" - } - ] - }, - "meta": { - "created": "2022-04-13T09:27:48Z", - "updated": "2022-04-13T09:28:34Z" - } -} -``` - -### Removing a Verification Method - -Verification methods and/or their relationships can be removed from the DID Document. The following code removes the verification method that we created previously. - - - - -```rust -account - .update_identity() - .delete_method() - .fragment("my-next-key") - .apply() - .await?; -``` - - - - -```js -await account.deleteMethod({ fragment: 'my-next-key' }); -``` - - - - -```json -{ - "doc": { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "capabilityInvocation": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#sign-0", - "controller": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z5k7vzMVuXXj8MJDcfzP2owvc8xKBA6BBsAkFf1GSNu2X" - } - ], - "service": [ - { - "id": "did:iota:6T4PRHWp7bNsKaBWr1gVtUBQfLaxAKqKGAeJWFBZkMyf#my-service-1", - "type": "MyCustomService", - "serviceEndpoint": "https://example.com/" - } - ] - }, - "meta": { - "created": "2022-04-13T09:27:48Z", - "updated": "2022-04-13T09:29:03Z" - } -} -``` - -Notice that the `capabilityDelegation` and `verificationMethod` properties are also removed from the DID Document since they became empty after the only verification method they contained and referenced was removed. - -Furthermore and similar to deleting verification methods, services can be deleted using `account.update_identity().delete_service()...` in Rust and `account.deleteService(..)` in JavaScript. - -:::tip -In this example, a message is published to the tangle every time the document is updated. These messages can be unnecessary. Instead, one message can be published that contains all the updates to the DID Document. -See the [lazy example for Rust](https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/account/lazy.rs) and [lazy example for JS](https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/src/lazy.ts) to learn more about lazy publishing. -::: diff --git a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/create.mdx b/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/create.mdx deleted file mode 100644 index a75fed17231..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/create.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: Create a Verifiable Credential -sidebar_label: Create and Sign -description: Explain how a VC is created and verified -image: /img/Identity_icon.png -keywords: - - verifiable - - credentials - - Create - - sign ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -A [verifiable credential (VC)](./overview.mdx) can represent all information that a physical credential represents, such as a passport or university degree. However, by allowing other parties to cryptographically verify the authorship and _integrity_ of the claims, verifiable credentials can be seen as more tamper-evident and more trustworthy than their physical counterparts. - -In the IOTA Identity Framework you can create a Verifiable Credential with the following properties: - -- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): list of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. -- [**Types**](https://www.w3.org/TR/vc-data-model/#types): list of types describing the credential. Includes `"VerifiableCredential"` by default. -- [**Subject**](https://www.w3.org/TR/vc-data-model/#credential-subject): the claims of the issuer; a set of objects that contain one or more properties that are each related to a subject. -- [**Issuer**](https://www.w3.org/TR/vc-data-model/#issuer): the identifier of the issuer, typically their DID. -- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): optional URI identifier for the credential. -- [**Issuance Date**](https://www.w3.org/TR/vc-data-model/#issuance-date): optional timestamp for expressing the date and time when a credential becomes valid. -- [**Expiration Date**](https://www.w3.org/TR/vc-data-model/#expiration): optional timestamp for expressing the date and time when a credential ceases to be valid. -- [**Status**](https://www.w3.org/TR/vc-data-model/#status): optional information used to determine the current status of a credential, i.e. whether or not it has been [revoked](./revocation.mdx). -- [**Schema**](https://www.w3.org/TR/vc-data-model/#data-schemas): optional list of objects specifying the schema that the data must conform to. -- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): optional link to a service where the recipient may refresh the included credentials. -- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. -- [**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](./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](./verifiable_presentations.mdx) for authentication purposes. - -Other metadata fields such as `challenge` and `domain` may be included, however they are more pertinent for [verifiable presentations](./verifiable_presentations.mdx). - -## Validation {#validation} - -Verifiers should ensure certain properties of a credential are valid when receiving one or more in a [verifiable presentation](./verifiable_presentations.mdx). Both issuers and holders may also wish to validate their credentials, particularly directly after creating or receiving one. Validation may be performed at any point in time and can be a useful way of checking whether a credential has expired or been revoked. - -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. -- **Optional validations**: additional checks on credential properties and the signature can be configured by specifying [Validation Options](#validation-options). - -### Validation Options {#validation-options} - -These options specify conditions that specific properties in a credential must satisfy. - -- **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). - -### Sharing Verifiable Credentials {#sharing-verifiable-credentials} - -A [verifiable presentation](./verifiable_presentations.mdx) is the recommended data format for sharing one or more verifiable credentials, as it provides cryptographic means of proving the DID of the holder presenting them, and for enforcing [subject-holder relationships](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships). See the [Verifiable Presentations](./verifiable_presentations.mdx) page for further detail. - -## Example - -The following code exemplifies how an issuer can create, sign, and validate a verifiable credential. In this example, the issuer signs a UniversityDegreeCredential with Alice's name and DID. -This Verifiable Credential can be [verified by anyone](./verifiable_presentations.mdx), allowing Alice to take control of it and share it with anyone. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/account/create_vc.rs -``` - - - - -```js reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/src/create_vc.ts -``` - - - - -> diff --git a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/overview.mdx b/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/overview.mdx deleted file mode 100644 index e4e8f10d884..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/overview.mdx +++ /dev/null @@ -1,48 +0,0 @@ ---- -title: Verifiable Credentials Overview -sidebar_label: Overview -description: Verifiable Credentials are statements about the holder. They can be verified online or in person, and the holder decides who to share them with. -image: /img/Identity_icon.png -keywords: - - verifiable - - credentials - - person ---- - -Credentials are statements about an entity, such as properties that the entity possesses or capabilities that they have (like drivers licences, passports, or a person's age). Verifiable Credentials (VCs) are statements (eg. Alice has a drivers licence) that can be cryptographically verified by a third party, either online or in person. Additionally, the holder of the VC decides what is shared and who it is shared with. - -There are several types of actors that play different roles in a verifiable credential system. We'll start with a common example of how things work in the world today using physical credentials and centralized databases, and outline the roles that various entities play in the Verifiable Credential system. - -:::tip Example - Passport Issuance - -A government (the _Issuer_) issues a passport asserting citizenship (the _Verifiable Credential_) to Alice (the _Subject_ and _Holder_), and writes the information to a database (the _Verifiable Data Registry_). When crossing the border, Alice (the _Holder_) presents her passport to a border agent (the _Verifier_) who can verify that Alice (the _Subject_) is indeed a citizen. - -::: - -**Subject:** An entity about which claims are made – Alice (the _Subject_) is a citizen of this country. - -**Holder:** An entity which possesses verifiable credentials – Alice (the _Holder_) possesses the passport (the _VC_). - -**Issuer:** An entity which asserts claims about a subject – The governing body (the _Issuer_), which is trusted, issues Alice a passport. - -**Verifier:** An entity which check's if the VC a holder presents is legitimate – The border agent (the _Verifier_) trusts the government (the _Issuer_) which issued Alice her passport, and validates that Alice (the _Subject_) is a citizen. - -:::note - -See the [Verifiable Credentials Data Model 1.0 Specification](https://w3c.github.io/vc-data-model/) for more information. - -::: - -### Verifiable Credentials in IOTA - -In the IOTA Identity framework, instead of a physical passport being given to Alice with the passport information being written into a centralized database owned by the government, Alice receives a digital verifiable credential, and the information required for verification in the future is written to the Tangle. - -At a high level, the creation and verification of a VC on IOTA works as follows: - -The first step is to create a verifiable credential which requires the subject (Alice) and issuer (the government) to have DIDs published to the Tangle, and a set of statements being asserted (that Alice has a passport). The issuer signs the credential with their private key and publishes the public key to the Tangle. - -Once the issuer is confident that the credential satisfies its expectation (after validating the credential's properties), the credential is stored and transmitted to the subject in a secure manner (off-chain). - -Validation is performed by looking up the issuer's public key on the Tangle, the holder proving ownership of their DID to the verifier (evidence), and validating that the credential has indeed been signed by the issuing party. - -The remaining chapters in this section explore creation, verification, and revocation of VCs in more detail. diff --git a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/revocation.mdx b/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/revocation.mdx deleted file mode 100644 index 8875a261f5e..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/revocation.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: Verifiable Credential Revocation -sidebar_label: Revocation -description: Explain how a VC can be revoked -image: /img/Identity_icon.png -keywords: - - verifiable - - credentials - - revoke - - revocation ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Overview - -The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential using the IOTA Identity Framework: - -1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking to a revocation bitmap, using the [`RevocationBitmap2022`](../../specs/revocation_bitmap_2022.mdx). -2. By removing the verification method that signed the credential. This invalidates all credentials that were signed with that verification method. - -## Revocation Bitmap - -One of the ways for an issuer to control the status of its credentials is by using a revocation list. At the most basic level, revocation information for all verifiable credentials issued by an issuer are expressed as simple binary values. The issuer keeps a list of all verifiable credentials it has issued in a bitmap. Each verifiable credential is associated with a unique index in the list. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. - -For example, with this approach the issuer adds an index to a credential in the `credentialStatus` field, such as `"5"`. This part of the credential might then look like this: - -```json -"credentialStatus": { - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", - "type": "RevocationBitmap2022", - "revocationBitmapIndex": "5" -}, -``` - -The verifier uses the `id` field (`did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation`) to look up the service in the issuer's DID document. This is an example of such a service: - -```json -{ - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", - "type": "RevocationBitmap2022", - "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" -} -``` - -During verification the verifier decodes the revocation bitmap embedded in the `data` url. This bitmap written as a bitstring looks like this: `000001`. Here, the 5th bit is set, which means the credential with that index is revoked, while all other credentials aren't revoked. - -## Removing the verification method - -A less efficient alternative is to remove the verification method that signed the credential from the DID Document of the issuer. This means the VC can no longer be validated. However, this would invalidate every VC signed with that verification method, meaning the issuer would have to sign every VC with a different key to retain precise control over which credential is revoked. - -## Example {#example} - -The following code exemplifies how you can revoke a [Verifiable Credential (VC)](overview.mdx). - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/account/revoke_vc.rs -``` - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/src/revoke_vc.ts -``` - - - diff --git a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/verifiable_presentations.mdx b/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/verifiable_presentations.mdx deleted file mode 100644 index 33b1f0632a8..00000000000 --- a/docs/build/identity.rs/0.6/docs/concepts/verifiable_credentials/verifiable_presentations.mdx +++ /dev/null @@ -1,184 +0,0 @@ ---- -title: Verifiable Presentations -sidebar_label: Verifiable Presentations -description: Explain how a VC is created and verified -image: /img/Identity_icon.png -keywords: - - verifiable - - presentations ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -A verifiable presentation is the recommended data format for sharing one or more [verifiable credentials](./overview.mdx). -It is constructed and signed by a holder to prove control over their credentials and can be presented to a verifier for [validation](#validation). - -For instance: after an issuer [creates and issues a verifiable credential](./create.mdx) to a holder, such as a university issuing a degree to a graduate, -the holder stores it securely until asked to present it. -A company could then request proof of that university degree: the holder can [create a verifiable presentation](#creation) -containing their credential, which is already signed by their university, and present it to the company to [validate](#validation). - -Note that verifiable presentations that contain personal data should, as with verifiable credentials, be transmitted and stored securely off-chain to satisfy data privacy regulations such as [GDPR](https://gdpr.eu/). - -:::note - -See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#presentations) for more information on verifiable presentations. - -::: - -## Creation {#creation} - -The IOTA Identity Framework enables holders to construct verifiable presentations easily. -As demonstrated in the [example](#example), holders need only pass in their credentials to present and sign the presentation. - -The following properties may be specified on a presentation: - -- [**ID**](https://www.w3.org/TR/vc-data-model/#identifiers): optional URI identifier for the presentation. -- [**Context**](https://www.w3.org/TR/vc-data-model/#contexts): list of JSON-LD context URIs. Includes `"https://www.w3.org/2018/credentials/v1"` by default. -- [**Types**](https://www.w3.org/TR/vc-data-model/#types): list of types describing the presentation. Includes `"VerifiablePresentation"` by default. -- [**Credentials**](https://www.w3.org/TR/vc-data-model/#dfn-verifiable-credentials): list of verifiable credentials to present. -- [**Holder**](https://www.w3.org/TR/vc-data-model/#dfn-holders): optional URI, typically a DID, of the entity that generated the presentation. -- [**Refresh Service**](https://www.w3.org/TR/vc-data-model/#refreshing): optional link to a service where the recipient may refresh the included credentials. -- [**Terms of Use**](https://www.w3.org/TR/vc-data-model/#terms-of-use): optional list of policies defining obligations, prohibitions, or permissions of the presentation recipient. - -Of the above, only the list of credentials is required when creating a presentation using the framework. -However, the holder property should be included to satisfy [subject-holder relationship](#subject-holder-relationship) checks during validation. - -After creation, the holder signs the verifiable presentation using a private key linked to one of the verification methods in their -DID Document and transmits it to a verifier for [validation](#validation). - -### Proof Options {#proof-options} - -A digital signature on a verifiable presentation both provides data _integrity_ and proves the DID of the holder. -The proof section embedded in a presentation 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 presentation was signed. -- **Expires**: timestamp after which the presentation is no longer considered valid. -- **Challenge**: arbitrary random string. Sent by the verifier and mitigates replay attacks; should be sufficiently random and uniquely generated per presentation request. -- **Domain**: arbitrary string. Sent by the verifier and can help mitigate replay attacks when used with a challenge. -- **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. - -:::note - -Verifiers should always send a challenge and domain to mitigate replay attacks, see [Security Considerations](#security-considerations). - -::: - -A verifier could also choose to ignore some or all of these options. -See [Proof Verifier Options](#proof-verifier-options) for more information. - -## Validation {#validation} - -The IOTA Identity Framework provides several options for verifiers to validate various sections of a verifiable presentation. -See the [example](#example) for a demonstration of how to validate a presentation. - -The framework checks: - -- **Semantic structure**: ensures the presentation and its credentials adhere to the specification. -- **Presentation proof**: verifies the presentation signature against the DID Document of the holder. -- **Credential proofs**: verifies the credential signatures against the DID Documents of their respective issuers. -- **Optional validations**: additional checks on signatures and credential fields can be configured by the verifier. - -Note that a verifier may specify which DID Documents to use for the holder and issuers, otherwise they are resolved from the Tangle automatically. - -Currently, the following are _not_ checked automatically: - -- **Data schemas**: credentials that specify a [schema](https://www.w3.org/TR/vc-data-model/#data-schemas) property should be examined to ensure conformance. -- **Fitness for purpose**: whether the credentials in a presentation and the data within them are acceptable and valid depends on the context in which they are used. Verifiers should ensure that the credential types, subjects, and schemas sent by a holder match what was requested. -- **Issuer trustworthiness**: verifiers must check that they trust the issuer on each individual credential in a presentation. The framework only verifies that the issuer's signature on each credential is current and valid against the given options. - -The default validation behaviour may be modified by the following options. - -### Proof Verifier Options {#proof-verifier-options} - -While the framework always verifies that the digital signature on a verifiable presentation is valid, a verifier may validate additional fields in the proof on a presentation. -Notably, to mitigate potential replay attacks a verifier should always check that the challenge and domain fields match what was sent to the holder when requesting the presentation. -See [Security Considerations](#security-considerations) for more information. - -The following options are available: - -- **Method Scope**: check the signing verification method has a particular [verification relationship](https://www.w3.org/TR/did-core/#verification-relationships). Overridden by the proof purpose check. -- **Method Type**: check the signing verification method has a particular type. -- **Challenge**: check the challenge field matches this string. -- **Domain**: check the domain field matches this string. -- **Proof Purpose**: require a specific purpose on the proof. See [Proof Options](#proof-options). -- **Allow Expired**: accept proofs where the current datetime is after their expiration. Default is to reject expired proofs. - -See [Proof Options](#proof-options) for more information on setting these properties as a holder when signing a verifiable presentation. - -### Subject-Holder Relationship {#subject-holder-relationship} - -Specifies the expected relationship between the holder that signed the verifiable presentation and the subject specified in each verifiable credential. -This can be restricted by the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property, -which indicates that a verifiable credential must only be encapsulated into a verifiable presentation whose holder matches the credential subject. - -By default, the framework always enforces that the holder matches the subject on all credentials. -The following options are available to modify that behaviour: - -- **`AlwaysSubject` (default)**: the holder DID that signed the presentation must match the [`credentialSubject` `id`](https://www.w3.org/TR/vc-data-model/#credential-subject) field in each of the attached credentials. This is the safest option which ensures holders may only present credentials that were directly issued to their DID. An error is thrown on a mismatch or if no subject `id` is present. -- **`SubjectOnNonTransferable`**: the holder DID must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. This is appropriate for accepting [bearer credentials](https://www.w3.org/TR/vc-data-model/#bearer-credentials) while still adhering to the specification. -- **`Any`**: the holder DID is not required to have any kind of relationship to any credential subject. This option performs no checks and ignores the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. - -:::note - -See the [Verifiable Credentials Data Model Specification](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) for further discussion on the different subject-holder relationships. - -::: - -### Credential Validation Options {#credential-validation-options} - -These options specify conditions that all credentials in a verifiable presentation must satisfy. - -- **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 the [`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**: see [Proof Verifier Options](#proof-verifier-options) for details. - -## Security Considerations {#security-considerations} - -### Replay Attacks {#replay-attacks} - -A verifiable presentation without challenge and domain properties 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). -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. - -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. - -Holders may additionally specify that their signature on a verifiable presentation expires after a short duration, as -per [Proof Options](#proof-options). However, verifiers and different implementations could choose to ignore that property, -so setting a signature expiration alone should not be relied upon. - -## Example {#example} - -The following code demonstrates how to use the IOTA Identity Framework end-to-end to create and sign a verifiable presentation as a holder, -serialize it to JSON for transmission, deserialize it on the receiving side as a verifier, and finally validate it with various options. - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/account/create_vp.rs -``` - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/src/create_vp.ts -``` - - - diff --git a/docs/build/identity.rs/0.6/docs/contact.mdx b/docs/build/identity.rs/0.6/docs/contact.mdx deleted file mode 100644 index b9603c18bba..00000000000 --- a/docs/build/identity.rs/0.6/docs/contact.mdx +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: Contact -sidebar_label: Contact -description: Get in touch with the project maintainers. -image: /img/Identity_icon.png -keywords: - - Contact - - GitHub - - Maintainers ---- - -If you found a security related issue, please follow the [responsible disclosure policy](https://github.com/iotaledger/identity.rs/security/policy). - -For everything else, you can get in contact with the project by: - -- Filing an issue on [GitHub](https://github.com/iotaledger/identity.rs). -- Joining the `identity` channel on the [IOTA Discord](https://discord.iota.org/). diff --git a/docs/build/identity.rs/0.6/docs/contribute.mdx b/docs/build/identity.rs/0.6/docs/contribute.mdx deleted file mode 100644 index 810107b0070..00000000000 --- a/docs/build/identity.rs/0.6/docs/contribute.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Contribute to the project -sidebar_label: Contribute -description: Contribute to IOTA Identity by joining the Identity initiative, via the projects GitHub repository, documentation, or sharing your knowledge. -image: /img/Identity_icon.png -keywords: - - Contribute - - GitHub - - Identity Initiative - - Documentation - - Discord - - reference ---- - -**Thanks for thinking about contributing to the project! You can contribute using the following ways.** - -## Join the Identity Initiative - -The [Identity Initiative](https://github.com/iota-community/X-Team_IOTA_Identity) is a collaborative effort to help improve the developer experience that includes: - -- Quality assurance and review. -- Documentation. -- Code samples. - -If you would like to get involved, join the [#x-team-identity](https://discord.com/channels/397872799483428865/773274309861834782) channel on [Discord](https://discord.iota.org). - -## Contribute to the Project's GitHub Repository - -All of the code is open source and hosted on [GitHub](https://github.com/iotaledger/identity.rs) where you can: - -- [Report a bug](https://github.com/iotaledger/identity.rs/issues/new/choose). -- [Suggest a new feature](https://github.com/iotaledger/documentation/blob/develop/.github/CONTRIBUTING.md). -- [Contribute to the documentation](/identity.rs/contribute#contribute-to-the-documentation). - -## Contribute to the Documentation - -This documentation is also open source and hosted on GitHub. - -If you want to contribute new documentation or fix an error, see the [contribution guidelines](https://github.com/iotaledger/documentation/blob/develop/.github/CONTRIBUTING.md). - -## Share your Knowledge - -Helping others is an important part of any open source ecosystem. - -By sharing your knowledge with others, you can provide a lot of value to the community and maybe inspire someone else to learn and contribute. - -Take a look at what discussions are going on in the #identity-discussion channel on [Discord](https://discord.iota.org). - -Thanks :heart: diff --git a/docs/build/identity.rs/0.6/docs/decentralized_identity.mdx b/docs/build/identity.rs/0.6/docs/decentralized_identity.mdx deleted file mode 100644 index 87a5a593c91..00000000000 --- a/docs/build/identity.rs/0.6/docs/decentralized_identity.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -description: Decentralized Identity defines a new method for identity management and authentication by removing centralized aspects. -image: /img/Identity_icon.png -keywords: - - Self Sovereign Identity - - decentralized - - Permissionless - - authentication - - explanation ---- - -# Introduction to Decentralized Identity - -![IOTA Decentralized Identity](/img/banner/banner_decentralized_identity.svg) - -Decentralized Identity or Self-Sovereign Identity (SSI) defines a new method for identity management and authentication. It removes the centralized aspects and puts the Identity subject in full control over its own identity. Decentralized Identity provides a solution for the increasing amount of database breaches, the lack of trust in any digital setting, and the increasingly difficult to comply with privacy legislation, such as GDPR. - -There are three levels of privacy when interacting on the internet: full privacy, verifiable identities, and pseudonymity. With full privacy, neither parties, nor observers, can identify the interacting parties. With verifiable identities, parties can trust each other because they can both provide proof about their identities. With pseudonymity, both parties recognize each other through a pseudonymous identifier. Pseudonymity is the default setting of the internet. However, data harvesting platforms, like -Google and Facebook, can now link these “random” identifiers, though imprecisely, to identities in the real world. The associated data and insights have become extremely valuable to advertising agencies, product developers, and numerous local and global businesses. - -The need for verifiable personal information can be fulfilled by digital identity. Digital identity allows users to bridge the gap between the online and the real world. When users provide personal information to someone online, in a “Bring Your Own Identity” (BYOI) manner, they will be able to prove that their personal information is perfectly accurate. Whereas in the current system, where companies like Google and Facebook provide an estimation of identity, there can be insufficient depth to user profiles or, in some cases, the information is altogether false. - -With digital identity, the user can decide what information to share and with whom they would like to share it. This will maintain and even improve online privacy, while allowing for new features and new business opportunities. Businesses will be able to trust BYOI information, enhancing interactions between company and customer, but also reducing fraudulent cases and endemic security risks. - - - -## Identity for People - -:::note - -IOTA Identity builds a new internet, without usernames, passwords, endless repeated forums, or uncontrolled data harvesting. - -::: - -Information about anyone's life is spread across many locations. Most people have numerous unorganized important documents at home, hundreds of online accounts, and many more online footprints. Through statistical predictive analysis, computer programs can harvest unverified online information sources and create a reasonably accurate profile about our lives. These profiles are accurate enough for targeted advertising and personalized content but lack the proof and trust for them to be used in business. This results in an antiquated customer experience where we have to submit our age and address for every purchase we make and every account we create. It also inhibits our ability to do many online tasks like requesting and extending licenses or taking out a mortgage. - -Self-Sovereign Identity is about returning autonomy and privacy to the individual, while also improving our online experience. Some movements focus on data privacy, preventing companies from using our information altogether, but with the IOTA Identity framework you control which part of the information you want to reveal. The user can create a single online profile containing all our personal information. They can decide who they share what information with, and a Verifier checks if the information is correct, making the data trustworthy. This moves their online profile from a statistical estimation by corporate entities to an accurate and verifiable profile under their own control. - -IOTA Identity allows a new internet without usernames, passwords, endless repeated forms, or data harvesting. Users have ultimate control and can choose to supply service providers with their personal data, who in return provide personalized experiences. Data will still flow, and perhaps even more than before, but it will always be in the interest of the individual, instead of a corporation. People will gain additional benefits in sharing their data, either in monetary value or improved customer experience. This sort of system is not possible in a non-neutral environment such as permissioned or fee-based ledgers. - -Governmental mechanisms for building _digital identities_ are currently being established throughout Europe and Asia, with demand increasing around the globe. However, they are managed by single entities and restricted to the governments that created them. By decentralizing a framework for these standards to adapt to, we have a system for intergovernmental verification of individuals and devices. A person’s digital identification will be transferable across borders like a passport. However, it will no longer require the trust of the issuing government due to the digital trust established by the open and auditable system. - -## Identity for Organizations - -:::note GDPR - -IOTA Identity allows organizations to comply with GDPR in a cost-efficient and privacy-enabling manner - -::: - -Corporations are associated with greed and abuse of power. This reputation stems from the role some have chosen to take within society. Corporations are trusted with our data, but often do not act responsibly; vulnerability, fix, patch, repeat. In software and systems, we have seen this cycle repeat. Headlines on data leaks are now an ever-present feature in the news. - -IOTA Identity presents an opportunity for companies to embrace a new role in the ecosystem. Traditional approaches do not provide cost-efficient solutions to new legislation like GDPR. IOTA Identity enables organizations to change their processes to comply with the new regulations in a cost-efficient and privacy-enabling manner. Features of “Data Protection and Privacy by Design” shift responsibility over Personal Identifiable Information (PII) from organization to customer, and organizations no longer need to store that data. The relationship between customer and organization is also tightened as communication via a third party Identity provider like Google or Facebook is no longer needed. - -Due to Know-Your-Customer (KYC) and Anti-Money Laundering (AML) obligations, companies can be certain who their customers are. These services also provide unique insight into the state of their customers’ data. These insights can be combined and translated into verifiable credentials, providing a new “Trust Anchor” service with a potential for new business models. KYC and AML credentials would return the autonomy of personal data back to the customer. Once companies accept the KYC and AML credentials of other companies, the enrollment time for new customers is significantly reduced, as are the costs. With the personal data secured by the customer, companies can afford to store less data in their own databases, reducing risk and responsibility and fulfilling the goals of legislation such as GDPR. - -Organizations that have their own decentralized identities can also combat fraud and increase control over their online brand. Companies can sign invoices and agreements using their decentralized identities. While interacting with the customers, they will also be able to reliably identify themselves. - -## Identity for Things - -:::note TRUST - -IOTA Identity adds the missing key ingredient for the "Economy of Things": Trust. - -::: - -With Identity of Things (IDoT), devices are provided with a unique global identity that are able to prove many attributes including their capabilities, specifications, and authenticity. People, organizations, and other devices will only pay devices that can prove their ability to fulfill the required task. This basis of trust prevents fraudulent activity. Additonally, by using the IOTA ledger, the progress of the task can be immutably logged. With the combination of the IOTA protocol and the IOTA Identity framework, we can automate the entire interaction between all parties, without requiring predefined trust. The [Industry Marketplace](https://industry.iota.org/) provides a perfect example of how this framework and level of autonomy work. - -There is a growth in applications that generate Digital Twins for physical devices or objects, such as the Asset Administration Shell (AAS) developed for our Industry Marketplace. Digital twins are online profiles representing a device or object. They provide a virtual state that mirrors reality by emulating the device or object’s physical state through data input sources like sensors. A digital twin is often used to monitor states and execute actions based on the information. Digital twins are only rarely shared outside the associated application and organization due to the complexities in sharing and matching profiles. However, empowered with a digital identity, digital twin sharing would become possible. Once data is verifiable and trusted, digital twins can form the basis for the digital representation of physical devices and objects. This allows other identities to interact with them automatically and provide services such as predictive maintenance. - -Security is a major barrier in advancing technologies that use IoT. Whether it is the smart devices in our own homes, or at a larger scale, the critical infrastructure of organizations and cities, security must be at the core. It is central to any globally-unifying identity solution. By integrating advanced research in cryptography and digital ledgers, and combining it with a scalable access and management system, security will become a core functionality of the systems we build. By using scalable device DIDs, integrating verification and reputation schemes, and allowing for transparent tamper-proof accountability, we begin to understand how we can future-proof the security of our systems, allowing us to start trusting the process, and not the patch. - -## One Framework. Any Identity - -:::note Framework - -The IOTA Identity framework serves as the invisible layer of trust for the internet. This framework must be open, scalable, and free, so that everyone and everything can enjoy trust as a basic digital right. - -::: - -With various types of actors requiring an identity protocol, it is a strong proposition to use the same underlying protocol for all of them. This IOTA Identity framework enables anyone or anything to create a digital identity, build an online profile of trust by collecting verifiable credentials, and share them with other actors they interact with. Interaction between people, companies, things, and objects becomes seamless. And just as we can trust a person, we will also be able to trust a car, or even a luxury coat. Different identities can also be linked together, creating trustworthy relationships, such as ownership of an object. IOTA already provides a protocol that enables these actors to transact value or data with one another. IOTA will now combine identity features into a single platform, creating the base protocol for the next generation of smart applications. - -## Why IOTA? - -:::note Neutral and Free - -IOTA is a neutral and free-to-use public infrastructure acting as a trustworthy public commons. - -::: - -IOTA is a scalable and feeless Distributed Ledger Technology (DLT). Similar to Blockchain technology, IOTA provides an immutable and decentralized ledger that can transact value through the IOTA token. Unlike Blockchain, IOTA uses a non-linear data structure called the [Tangle](/learn/about-iota/an-introduction-to-iota#the-tangle-data-structure) which makes it feeless and vastly more scalable. The Tangle also facilitates feeless transactions of data, such as DID registrations and credential revocations. As a single source of truth and trust in data, the Tangle can provide the trust infrastructure in a highly networked world. - -IOTA is uniquely suited for a single unifying identity implementation. The network is designed for both humans and devices, providing a platform for trusted communication between individuals, organizations, and things. The IOTA Foundation’s principles of full transparency, openness, and permissionless innovation provide an open and neutral environment: - -1. **Permissionless & Decentralized**: Unlike a permissioned network such as Hyperledger or Corda, everyone can participate in consensus without being granted access. No party incentivized by profit-making has collective control over the network (unlike all blockchains). This makes IOTA neutral and censorship-resistant. -2. **Public**: Everyone can observe (unless using optional encryption) the transactions in the network. The network is inherently transparent. -3. **Feeless**: All data and _value transactions_ on the network are free. Unlike other DLTs such as Bitcoin or Ethereum, registration and communication of identities can be written to the network without a requirement to purchase a _cryptocurrency_ token. -4. **Open Source**: Everyone can view and contribute to the code. -5. **Easy to use**: IOTA Identity is inherently easier to use due to the lack of fees or requirements to set up an entire private network. In addition, the framework is designed to have an easy to use high-level API, with accessibility to the low-level, more complex and more flexible API. Through integration with the [Stronghold](/stronghold.rs/welcome 'Stronghold is an open-source software library that was originally built to protect IOTA Seeds, but can be used to protect any digital secret.') project, we also provide out-of-the-box security for secrets. - -Data must be immutably stored on a distributed ledger to ensure the decentralized nature of the digital identity protocol. With the network’s continual uptime, credentials are always verifiable without a dependency on the servers of credential issuers. This system also increases individual privacy, because contact with the Issuer is removed from the interaction between Holder and Verifier. Issuers will not be able to track when and how often the Holder uses their credentials. The flexibility afforded from the Tangle means that the digital identity framework remains extendable in the future. - -Within the digital identity framework, the Tangle is used for the following functionalities: - -1. **Public Key Registry**: The Tangle enables a decentralized public key infrastructure (DPKI) for Issuers using DID standards. This allows Verifiers to verify a signature without reliance on a centralized server. The DID standard also adds service endpoints, extending the usability of Identities beyond a public key registry, to, for example, registering verifiable credential standards. -2. **Revocation**: A verifiable credential can be revoked, meaning it will no longer be able to pass verification. The revocation is immutably stored on the Tangle, making sure no Holder can attempt to use their revoked credentials. This is designed to be a simple public key deactivation to guarantee GDPR compliance. diff --git a/docs/build/identity.rs/0.6/docs/faq.mdx b/docs/build/identity.rs/0.6/docs/faq.mdx deleted file mode 100644 index b3da95f0e4b..00000000000 --- a/docs/build/identity.rs/0.6/docs/faq.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Frequently Asked Questions -sidebar_label: FAQ -description: Frequently Asked Question regarding IOTA Identity. -image: /img/Identity_icon.png -keywords: - - FAQ - - Frequently Asked Question - - Troubleshooting - - IOTA Identity ---- - -This page contains frequently asked questions regarding the Identity Library and Self Sovereign Identity in general. - -### What programming languages are supported by the IOTA Identity framework? - -We currently provide a Rust library and a JavaScript library for both the browser and Node.js via WebAssembly (Wasm) bindings. See the "Programming Languages" section for more information. - -### Do I need to have IOTA tokens to start building with IOTA Identity? - -At the moment you don't need IOTA tokens to create and manage identities, although we are exploring opportunities to utilize the token in the future. - -### How do I prove control over my DID? - -Control over an identity is ultimately tied to the control over cryptographic key material (something you have). - -### How do I store my private keys? - -Theoretically you can store the keys however you like. We provide a secure default using IOTA Stronghold where possible, which is a secure software implementation for isolating digital secrets with encrypted storage. For even better guarantees you could look into hardware based key storage. - -### Do I need a Permanode to use IOTA Identity? - -You can get started without one but currently you do require access to a Permanode (a node which stores the entire history of the Tangle) to reliably resolve identities in production. The trustworthiness of this node is very important, since a malicious node could respond with outdated identities, so ideally you should run one yourself or ensure the party supplying the node is trustworthy. - -### Can I use IOTA Identity on Android or iOS? - -We currently do not supply dedicated bindings for Kotlin or Swift. There has been some success running the Wasm bindings on mobile, however. - -### Can I use IOTA Identity on embedded devices? - -We currently do not supply dedicated bindings catering to embedded devices with restricted capabilities. You can try to compile the Rust library for your target platform or use a gateway in front of the devices to handle IOTA Identity interactions. - -### What should I do if my private key is compromised? - -If you still have control over your identity, rotate the key material ASAP! If an attacker has locked you out of your identity, there is not much you can do. Notify contacts that your identity has been compromised and start fresh with a new one. It is for this reason that we suggest using different keys for day-to-day signing and authentication operations, and instead store private keys capable of performing updates to your DID Document securely and separately. - -### Are verifiable credentials stored on the Tangle? - -Verifiable credentials, particularly those with personal identifiable information, are supposed to be stored securely off-Tangle on user devices or systems. As a user, you are in charge of storing your credentials securely and sharing them with other parties on a need-to-know basis. - -### Do I need to hide my DID? Will people be able to identify me by my DID? - -A DID Document should not contain any information linking back to you as a person. However, there is the chance of entities correlating information about you from your DID if used across multiple issuers and verifiers. To minimize this risk, it is advisable to use different DIDs for different use-cases. diff --git a/docs/build/identity.rs/0.6/docs/getting_started/create_and_publish.mdx b/docs/build/identity.rs/0.6/docs/getting_started/create_and_publish.mdx deleted file mode 100644 index 29a5757f22e..00000000000 --- a/docs/build/identity.rs/0.6/docs/getting_started/create_and_publish.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Create a Decentralized Identity -sidebar_label: Create a DID Document -description: Create DID Documents and publish them to the Tangle -image: /img/Identity_icon.png -keywords: - - Documents - - DID - - Tangle - - Create - - Publish ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -If you want to benefit from Self-Sovereign Identity, you need to create a [Decentralized Identity](../concepts/decentralized_identifiers/overview.mdx). This identity consists of many parts that have different functions. This page will cover the basics about identity creation and publishing to the Tangle. - -## Identity Generation Process - -The generation of an identity starts with a randomly generated [asymmetric key pair](https://en.wikipedia.org/wiki/Public-key_cryptography). You can generate it with the IOTA Identity framework, or you can provide it as a parameter during the creation process. The public key is hashed using the [`Blake2b-256` algorithm](). This hash becomes the DID, creating a permanent and provable link between the initial keypair and the DID. The public key is then embedded into the initial DID Document and is used for verifying signatures created with the corresponding private key. - -## Using the Account Module - -The following example uses the high-level account module of the IOTA Identity framework to create an identity. You should use the account module for most of your use cases, but a lower-level API is also available should you need more flexibility at the cost of more complexity. For more information on APIs please visit the [Rust API Reference](../libraries/rust/getting_started.mdx#api-reference) or the [WASM API Reference](../libraries/wasm/api_reference.mdx). - -:::tip Using Replit - -Select your programming language of choice and press the green play button to execute the example. - -::: - - - - -```ts reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/src/create_did.ts -``` - - - - -```rust reference -https://github.com/iotaledger/identity.rs/blob/support/v0.6/examples/account/create_did.rs -``` - - - - -The first step in this example is the creation of an account. The account is a stateful object that manages one or more identities. The account provides an interface to execute high-level operations on identities, such as [creating](../concepts/decentralized_identifiers/create.mdx) and [updating](../concepts/decentralized_identifiers/update.mdx)) them. - -Next, the identity is created and published to the IOTA Tangle. This operation will: - -1. Generate a private key. -2. Store it in the account. -3. Generate a DID. -4. Generate a DID Document. -5. Publish it to the Tangle. - -Once the DID Document is uploaded to the Tangle, it becomes immutable, meaning that this version of the identity can never be altered or removed. The only way to update or delete an identity is by publishing a new version, which we will discuss in the next section. This immutability is what makes a Decentralized Identity solution based on Distributed Ledger Technology (DLT) trustworthy. The public keys inside the DID Document can never be changed without having access to the private key, allowing the users to completely control their own identities. - -The rest of the example shows how to retrieve (resolve) the identity from the Tangle and how it can be deleted. diff --git a/docs/build/identity.rs/0.6/docs/getting_started/install.mdx b/docs/build/identity.rs/0.6/docs/getting_started/install.mdx deleted file mode 100644 index dc165f7412c..00000000000 --- a/docs/build/identity.rs/0.6/docs/getting_started/install.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -description: Install the IOTA Identity Rust Library or its WASM binding in a few simple steps -image: /img/Identity_icon.png -sidebar_label: Install the Library -title: Install the Library -keywords: - - Identity - - install - - npm - - cargo - - Rust - - WASM ---- - -## Rust - -### Requirements - -- [Rust](https://www.rust-lang.org/tools/install) -- [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html) - -### Include the Library - -You can include the IOTA Identity Library in your project by adding it as a dependency in your `Cargo.toml`. - -#### Latest Stable Release - -This version is published to crates.io and is **stable**, following semantic versioning. - -```toml -[dependencies] -identity_iota = { version = "0.6" } -``` - -#### Development Release - -This version matches the `dev` branch of this repository. It has all the **latest features**, but as such it **may also have undocumented breaking changes**. - -```toml -[dependencies] -identity_iota = { git = "https://github.com/iotaledger/identity.rs", branch = "dev"} -``` - -You can find detailed installation instructions in the [Getting Started With Rust](../libraries/rust/getting_started.mdx) section. - -## WASM - -### Requirements - -- [Npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) -- [Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm) - -### Install the Library - -You can install the WASM binding of the IOTA Identity Library using [npm](https://www.npmjs.com/). - -#### Latest Stable Release - -This version published to npm is **stable**, following semantic versioning. - -```bash -npm install @iota/identity-wasm -``` - -#### Development Release - -This version matches the `dev` branch of this repository. It has all the **latest features**, but as such it **may also have undocumented breaking changes**. - -```bash -npm install @iota/identity-wasm@dev -``` - -You can find detailed installation instructions in the [Getting Started With WASM](../libraries/wasm/getting_started.mdx) section. diff --git a/docs/build/identity.rs/0.6/docs/getting_started/overview.mdx b/docs/build/identity.rs/0.6/docs/getting_started/overview.mdx deleted file mode 100644 index 2220e3deca9..00000000000 --- a/docs/build/identity.rs/0.6/docs/getting_started/overview.mdx +++ /dev/null @@ -1,40 +0,0 @@ ---- -description: Using IOTA Identity, a new digital identity can be created by anyone or anything at any time by generating a Decentralized Identifier (DID) combined with Verifiable Credentials -image: /img/Identity_icon.png -keywords: - - Identity - - verifiable - - credentials - - Rust - - WASM - - reference ---- - -# Overview - -![Identity getting started](/img/banner/banner_identity_getting_started.svg) - -Using the [standards proposed by W3C](https://www.w3.org/TR/did-core/), this section explains the IOTA Identity implementation. You can use this implementation to create a new digital identity for anyone or anything at any time. To do so, you must first generate a [Decentralized Identifier (DID)](../concepts/decentralized_identifiers/overview.mdx) that will serve as a reference to the [DID Document](../concepts/decentralized_identifiers/overview.mdx#did-documents). The DID Document contains public keys and other mechanisms to enable the subject to prove their association with the DID. - -However, you cannot tell much about the subject from a DID. You need to combine the DID with [Verifiable Credentials](../concepts/verifiable_credentials/overview.mdx). Verifiable Credentials are statements about the creator of the DID. They can be shared and verified online in a "Bring Your Own Identity" (BYOI) manner, and the DID creator remains in complete control of the process. - -You can use this framework in processes such as: - -- Address validation: Customers can prove where they live for shipping and billing addresses. -- Age verification: Customers can prove they are 18+ for online purchases. -- (Authority) Login: Customers can prove who they are and gain access to their account, - without passwords. This can be useful for many websites, including eGovernment and - banking. - -## Implementations - -The IOTA Identity framework is developed in the Rust programming language. We also provide bindings, or "Foreign Function Interfaces" (FFI), to other languages. The full set of language bindings currently available is: - -- [Rust](../libraries/rust/getting_started.mdx) -- [WASM](../libraries/wasm/getting_started.mdx) - -## Applications - -The following applications are currently utilizing the IOTA Identity framework: - -- [Selv app](https://selv.iota.org/) diff --git a/docs/build/identity.rs/0.6/docs/glossary.mdx b/docs/build/identity.rs/0.6/docs/glossary.mdx deleted file mode 100644 index 512d4afc6fb..00000000000 --- a/docs/build/identity.rs/0.6/docs/glossary.mdx +++ /dev/null @@ -1,140 +0,0 @@ ---- -description: Glossary for IOTA Identity, defines the terms used in this specification and throughout decentralized identifier infrastructure. -image: /img/Identity_icon.png -keywords: - - W3C - - terminology - - IOTA - - verification method - - verifiable data registry - - reference ---- - -# Glossary - -This section defines the terms used in this specification, [sourced from W3](https://www.w3.org/TR/did-core/#terminology), and throughout decentralized identifier infrastructure. A link to these terms is included whenever they appear in this specification. - -The first part of the glossary describes the terminology by the W3C. The [second describes](#iota-terminology) the terminology for IOTA-related topics. - -## W3C Terminology - -### Authentication - -A process (typically some type of protocol) by which an entity can prove it has a specific attribute or controls a specific secret using one or more verification methods. With DIDs, a common example would be proving control of the private key associated with a public key published in a DID document. - -### Decentralized Identifier (DID) - -A globally unique persistent identifier that does not require a centralized registration authority because it is generated or registered cryptographically. The generic format of a DID is defined in the DID Core specification. A specific DID scheme is defined in a DID method specification. Many, but not all, DID methods make use of distributed ledger technology (DLT) or some other form of decentralized network. - -### Decentralized Identity Management - -An type of identity management that is based on the use of decentralized identifiers. Decentralized identity management extends authority for identifier generation, registration, and assignment beyond traditional roots of trust such as X.500 directory services, the Domain Name System, and most national ID systems. - -### DID Controller - -An entity that has the capability to make changes to a DID document. A DID may have more than one DID controller. The DID controller(s) can be denoted by the optional controller property at the top level of the DID document. Note that one DID controller may be the DID subject. - -### DID Delegate - -An entity to whom a DID controller has granted permission to use a verification method associated with a DID via a DID document. For example, a parent who controls a child's DID document might permit the child to use their personal device for authentication purposes. In this case, the child is the DID delegate. The child's personal device would contain the private cryptographic material enabling the child to authenticate using the DID. However, the child may not be permitted to add other personal devices without the parent's permission. - -### DID Document - -A set of data describing the DID subject, including mechanisms, such as public keys and pseudonymous biometrics, that the DID subject or a DID delegate can use to authenticate itself and prove its association with the DID. A DID document may also contain other attributes or claims describing the DID subject. A DID document may have one or more different representations as defined in § 6. Core Representations or in the W3C DID Specification Registries [DID-SPEC-REGISTRIES]. - -### DID Fragment - -The portion of a DID URL that follows the first hash sign character (#). DID fragment syntax is identical to URI fragment syntax. - -### DID Method - -A definition of how a specific DID scheme must be implemented to work with a specific verifiable data registry. A DID method is defined by a DID method specification, which must specify the precise operations by which DIDs are created, resolved and deactivated, where DID documents are written and updated. See § 7. Methods. - -### DID Path - -The portion of a DID URL that begins with and includes the first forward-slash (/) character and ends with either a question mark (?) character or a fragment hash sign (#) character (or the end of the DID URL). DID path syntax is identical to URI path syntax. See § 3.2.3 Path. - -### DID Query - -The portion of a DID URL that follows and includes the first question mark character (?). DID query syntax is identical to URI query syntax. See § 3.2.4 Query. - -### DID Resolution - -The function that takes, as an input, a DID and a set of input metadata and returns a DID document in a conforming representation plus additional metadata. This function relies on the "Read" operation of the applicable DID method. The inputs and outputs of this function are defined in § 8. Resolution. - -### DID Resolver - -A DID resolver is a software or hardware component that performs the DID resolution function by taking a DID as input and producing a conforming DID document as output. - -### DID Scheme - -The formal syntax of a decentralized identifier. The generic DID scheme begins with the prefix "did:" as defined in the section of the DID Core specification. Each DID method specification must define a specific DID scheme that works with that particular DID method. In a specific DID method scheme, the DID method name must follow the first colon and terminate with the second colon, such as "did:example:". - -### DID Subject - -The entity identified by a DID and described by a DID document. A DID has exactly one DID subject. Anything can be a DID subject: a person, group, organization, physical thing, digital thing, logical thing, and so on. - -### DID URL - -A DID plus any additional syntactic component that conforms to the definition in § 3.2 DID URL Syntax. This includes an optional DID path, optional DID query (and its leading ? character), and optional DID fragment (and its leading # character). - -### DID URL Dereferencing - -The function that takes as its input a DID URL, a DID document, plus a set of dereferencing options, and returns a resource. This resource may be a DID document plus additional metadata, or it may be a secondary resource contained within the DID document, or it may be a resource entirely external to the DID document. If the function begins with a DID URL, it uses the DID resolution function to fetch a DID document indicated by the DID contained within the DID URL. The dereferencing function can then perform additional processing on the DID document to return the dereferenced resource indicated by the DID URL. The inputs and outputs of this function are defined in § 8.2 DID URL Dereferencing. - -## IOTA Terminology - -### Distributed Ledger (DLT) - -A distributed database in which the various nodes use a consensus protocol to maintain a shared ledger in which each transaction is cryptographically signed and chained to the previous transaction. - -### Public Key Description - -A data object contained inside a DID document that contains all the metadata necessary to use a public key or verification key. - -### Resource - -As defined by [RFC3986]: "...the term 'resource' is used in a general sense for whatever might be identified by a URI." Similarly, any resource may serve as a DID subject identified by a DID. - -### Representation - -As defined for HTTP by [RFC7231]: "information that is intended to reflect a past, current, or desired state of a given resource, in a format that can be readily communicated via the protocol, and that consists of a set of representation metadata and a potentially unbounded stream of representation data." A DID document is a representation of information describing a DID subject. The § 6. Core Representations section of the DID Core specification defines several representation formats for a DID document. - -### Service - -A means of communicating or interacting with the DID subject or associated entities via one or more service endpoints. Examples include discovery services, agent services, social networking services, file storage services, and verifiable credential repository services. - -### Service Endpoint - -A network address (such as an HTTP URL) at which a service operates on behalf of a DID subject. - -### Uniform Resource Identifier (URI) - -The standard identifier format for all resources on the World Wide Web as defined by [RFC3986]. A DID is a type of URI scheme. - -### Verifiable Credential - -A standard data model and representation format for cryptographically-verifiable digital credentials as defined by the W3C [VC-DATA-MODEL]. - -### Verifiable Data Registry - -A system that facilitates the creation, verification, updating, or deactivation of decentralized identifiers and DID documents. A verifiable data registry may also be used for other cryptographically-verifiable data structures such as verifiable credentials. For more information, see [VC-DATA-MODEL]. - -### Verifiable Timestamp - -A verifiable timestamp enables a third-party to verify that a data object existed at a specific moment in time and that it has not been modified or corrupted since that moment in time. If the data integrity were to be reasonably modified or corrupted since that moment in time, the timestamp is not verifiable. - -### Verification Method - -A set of parameters that can be used together with a process or protocol to independently verify a proof. For example, a public key can be used as a verification method with respect to a digital signature; in such usage, it verifies that the signer possessed the associated private key. - -"Verification" and "proof" in this definition are intended to apply broadly. For example, a public key might be used during Diffie-Hellman key exchange to negotiate a shared symmetric key for encryption. This guarantees the integrity of the key agreement process. It is thus another type of verification method, even though descriptions of the process might not use the words "verification" or "proof." - -### Verification Relationship - -An expression of the relationship between the DID subject and a verification method. An example of a verification relationship is § 5.4.1 authentication. - -### Universally Unique Identifier (UUID) - -A type of globally unique identifier defined by [RFC4122]. UUIDs are similar to DIDs in that they do not require a centralized registration authority. UUIDs differ from DIDs in that they are not resolvable or cryptographically-verifiable. -In addition to the terminology above, this specification also uses terminology from the [INFRA] specification to formally define the abstract data model. When [INFRA] terminology is used, such as string, ordered set, and map, it is linked directly to that specification. diff --git a/docs/build/identity.rs/0.6/docs/introduction.mdx b/docs/build/identity.rs/0.6/docs/introduction.mdx deleted file mode 100644 index 422e07db2c1..00000000000 --- a/docs/build/identity.rs/0.6/docs/introduction.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -description: The most important concepts that developers will need to know to utilize IOTA Identity to its full potential. -image: /img/Identity_icon.png -keywords: - - Identity - - guide - - TOC - - overview - - reference ---- - -# IOTA Identity Framework Guide - -![IOTA Identity](/img/banner/banner_identity.svg) - -The IOTA Identity framework implements the most common standards and patterns for Decentralized Identity in both a DLT agnostic and `iota` method specification manner. It is designed to work for Identity for People, Organizations, Things, and Objects acting as a unifying-layer of trust between everyone and everything. - -In this guide, we will go through the most important concepts that developers will need to know to utilize IOTA Identity to its full potential. - -## Overview - -### [Chapter 1: Decentralized Identity](./decentralized_identity.mdx) - -Describes the concept of Decentralized or Self-Sovereign Identities (SSI), how it applies to People, Organizations and Things, and why IOTA is used. - -### [Chapter 2: Getting Started](./getting_started/overview.mdx) - -Gives a quick overview of how to install the library and creating your first DID. - -### Chapter 3: Concepts - -Describes relevant concepts of SSI and how to utilize them in the library. - -### [Chapter 3.1: Decentralized Identifiers (DID)](./concepts/decentralized_identifiers/overview.mdx) - -Explains the DID standard from W3C and how to manipulate DID Documents. - -### [Chapter 3.2: Verifiable Credentials (VC)](./concepts/verifiable_credentials/overview.mdx) - -Explains the VC standard from W3C, how to create and revoke VCs, and how to use Verifiable Presentations. - -### [Chapter 3.3: Advanced Concepts](./concepts/advanced/overview.mdx) - -This chapter is meant for those that want to push the IOTA Identity framework to its limits, utilizing the more complex, yet more flexible lower-level libraries, allowing developers to optimize their implementation, take control over storage/security, and add features to the framework. - -### [Chapter 4: Programming Languages](./libraries/overview.mdx) - -While the framework itself is developed in the Rust programming language, we also provide bindings, or "Foreign Function Interfaces" (FFI), to other languages. These will have separate getting started sections, making the rest of the guide language agnostic, focusing on the conceptual level. - -### [Chapter 5: Tutorials](./tutorials/overview.mdx) - -Contains end-to-end examples using the library to achieve common use-cases. - -### [Chapter 6: Specification](./specs/overview.mdx) - -While IOTA Identity implements many existing standards, it also adds some additional features we would like to standardize ourselves. This chapter covers these features and how they work in great detail. These are not light reads and can be skipped. - -### [Chapter 7: Glossary](./glossary.mdx) - -A list of all terminology used in this guide, the framework, and all materials surrounding it. - -### [Chapter 8: Contribute](./contribute.mdx) - -A simple guide on how to contribute to the framework. - -### [Chapter 9: Workflow](./workflow.mdx) - -An overview of the workflow to design, develop and release the framework. - -### [Chapter 10: Contact](./contact.mdx) - -How to contact the maintainers. - -### [Chapter 11: FAQ](./faq.mdx) - -Overview of the most Frequently Asked Questions and their answers. diff --git a/docs/build/identity.rs/0.6/docs/libraries/overview.mdx b/docs/build/identity.rs/0.6/docs/libraries/overview.mdx deleted file mode 100644 index 0a9bb2ff187..00000000000 --- a/docs/build/identity.rs/0.6/docs/libraries/overview.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Libraries Overview -sidebar_label: Overview -description: Provide overview of the libraries -image: /img/Identity_icon.png -keywords: - - libraries ---- - -While the framework itself is developed in the Rust programming language, we also provide bindings, or "Foreign Function Interfaces" (FFI), to other languages. - -For the Rust implementation see the [Rust Getting Started](./rust/getting_started.mdx). - -For the Wasm bindings see the [Wasm Getting Started](./wasm/getting_started.mdx). diff --git a/docs/build/identity.rs/0.6/docs/libraries/rust/getting_started.mdx b/docs/build/identity.rs/0.6/docs/libraries/rust/getting_started.mdx deleted file mode 100644 index b3f0f2cb5f1..00000000000 --- a/docs/build/identity.rs/0.6/docs/libraries/rust/getting_started.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Getting Started with Rust -sidebar_label: Getting Started -description: Getting started with the IOTA Identity Rust Library. -image: /img/Identity_icon.png -keywords: - - Rust - - Identity ---- - -## Requirements - -- [Rust](https://www.rust-lang.org/) (>= 1.60) -- [Cargo](https://doc.rust-lang.org/cargo/) (>= 1.60) - -## Include the Library - -To include IOTA Identity in your project add it as a dependency in your `Cargo.toml`: - -### Latest Stable Release - -This version is published to crates.io and is **stable**, following semantic versioning. - -```toml -[dependencies] -identity_iota = { version = "0.6" } -``` - -### Development Release - -This version matches the `dev` branch of this repository. It has all the **latest features**, but as such it **may also have undocumented breaking changes**. - -```toml -[dependencies] -identity_iota = { git = "https://github.com/iotaledger/identity.rs", branch = "dev"} -``` - -## Examples - -To try out the [examples](https://github.com/iotaledger/identity.rs/tree/main/examples), you should: - -1. Clone the repository: - -```bash -git clone https://github.com/iotaledger/identity.rs -``` - -2. Build the repository: - -```bash -cargo build -``` - -3. Run your first example: - -```bash -cargo run --example getting_started -``` - -## API Reference - -The API reference for the Rust library can be found on [docs.rs](https://docs.rs/identity_iota/0.6.1/identity_iota/index.html). - -If you would like to build the documentation locally you can do so with the following command: - -``` -RUSTDOCFLAGS='--cfg docsrs' cargo +nightly doc -p identity_iota --all-features --no-deps --open -``` diff --git a/docs/build/identity.rs/0.6/docs/libraries/wasm/api_reference.mdx b/docs/build/identity.rs/0.6/docs/libraries/wasm/api_reference.mdx deleted file mode 100644 index af35c9b6787..00000000000 --- a/docs/build/identity.rs/0.6/docs/libraries/wasm/api_reference.mdx +++ /dev/null @@ -1,5937 +0,0 @@ ---- -title: WASM API Reference -sidebar_label: API Reference -description: WASM API reference. -image: /img/Identity_icon.png -keywords: - - WASM - - API Reference ---- - -## Classes - -
-
- Account -
-
-

An account manages one identity.

-

- It handles private keys, writing to storage and publishing to the Tangle. -

-
-
- AccountBuilder -
-
-

- An [Account] builder for easy account configuration. -

-

- To reduce memory usage, accounts created from the same builder share the - same Storage - used to store identities, and the same Client used to - publish identities to the Tangle. -

-

- The configuration on the other hand is cloned, and therefore unique for - each built account. This means a builder can be reconfigured in-between - account creations, without affecting the configuration of previously built - accounts. -

-
-
- AgreementInfo -
-
-

Agreement information used as the input for the concat KDF.

-
-
- AutoSave -
-
-
- CekAlgorithm -
-
-

- Supported algorithms used to determine and potentially encrypt the content - encryption key (CEK). -

-
-
- ChainState -
-
-
- Client -
-
-
- Credential -
-
-
- CredentialValidationOptions -
-
-

Options to declare validation criteria when validating credentials.

-
-
- CredentialValidator -
-
-
- DID -
-
-
- DIDUrl -
-
-
- - DiffChainHistory - -
-
-
- - DiffMessage - -
-
-

- Defines the difference between two DID Documents' JSON - representations. -

-
-
- Document -
-
-
- DocumentHistory -
-
-

A DID Document's history and current state.

-
-
- DocumentMetadata -
-
-

Additional attributes related to an IOTA DID Document.

-
-
- Duration -
-
-

A span of time.

-
-
- Ed25519 -
-
-
- EncryptedData -
-
-

The structure returned after encrypting data

-
-
- EncryptionAlgorithm -
-
-

Supported content encryption algorithms.

-
-
- ExplorerUrl -
-
-
- IntegrationChainHistory -
-
-
- KeyLocation -
-
-

The storage location of a verification method key.

-

- A key is uniquely identified by the fragment and a hash of its public key. - Importantly, the fragment alone is insufficient to represent the storage - location. For example, when rotating a key, there will be two keys in - storage for the same identity with the same fragment. The{' '} - key_hash disambiguates the keys in situations like these. -

-

- The string representation of that location can be obtained via{' '} - canonicalRepr. -

-
-
- KeyPair -
-
-
- MethodContent -
-
-
- MethodData -
-
-

Supported verification method data formats.

-
-
- MethodScope -
-
-

Supported verification method types.

-
-
- MethodType -
-
-

Supported verification method types.

-
-
- Network -
-
-
- Presentation -
-
-
- PresentationValidationOptions -
-
-

Options to declare validation criteria when validating presentation.

-
-
- PresentationValidator -
-
-
- Proof -
-
-

A digital signature.

-

- For field definitions see:{' '} - - https://w3c-ccg.github.io/security-vocab/ - -

-
-
- ProofOptions -
-
-

- Holds additional options for creating signatures. See{' '} - IProofOptions. -

-
-
- ProofPurpose -
-
-

- Associates a purpose with a Proof. -

-

- See{' '} - - https://w3c-ccg.github.io/security-vocab/#proofPurpose - -

-
-
- Receipt -
-
-
- ResolvedDocument -
-
-

- An IOTA DID document resolved from the Tangle. Represents an integration - chain message possibly merged with one or more DiffMessages. -

-
-
- Resolver -
-
-
- ResolverBuilder -
-
-

- Builder for configuring [Clients][Client] when constructing a - [Resolver]. -

-
-
- RevocationBitmap -
-
-

A compressed bitmap for managing credential revocation.

-
-
- Service -
-
-

- A DID Document Service used to enable trusted interactions associated with - a DID subject. -

-

- See:{' '} - - https://www.w3.org/TR/did-core/#services - -

-
-
- Signature -
-
-
- StorageTestSuite -
-
-

- A test suite for the Storage interface. -

-

- This module contains a set of tests that a correct storage implementation - should pass. Note that not every edge case is tested. -

-

- Tests usually rely on multiple interface methods being implemented, so - they should only be run on a fully implemented version. That's why - there is not a single test case for every interface method. -

-
-
- Timestamp -
-
-
- VerificationMethod -
-
-
- VerifierOptions -
-
-

- Holds additional proof verification options. See{' '} - IVerifierOptions. -

-
-
- X25519 -
-
-

- An implementation of X25519 Elliptic-curve Diffie-Hellman - (ECDH) cryptographic key exchange. -

-
-
- -## Members - -
-
- DIDMessageEncoding -
-
-
- StatusCheck -
-
-

- Controls validation behaviour when checking whether or not a credential - has been revoked by its - - credentialStatus - . -

-
-
- Strict -
-
-

- Validate the status if supported, reject any unsupported - - credentialStatus - types. -

-

- Only RevocationBitmap2022 is currently supported. -

-

This is the default.

-
-
- SkipUnsupported -
-
-

- Validate the status if supported, skip any unsupported - - credentialStatus - types. -

-
-
- SkipAll -
-
-

Skip all status checks.

-
-
- SubjectHolderRelationship -
-
-

- Declares how credential subjects must relate to the presentation holder - during validation. See{' '} - PresentationValidationOptions::subject_holder_relationship. -

-

- See also the{' '} - - Subject-Holder Relationship - {' '} - section of the specification. -

-
-
- AlwaysSubject -
-
-

- The holder must always match the subject on all credentials, regardless of - their{' '} - - nonTransferable - {' '} - property. This variant is the default used if no other variant is - specified when constructing a new - PresentationValidationOptions. -

-
-
- SubjectOnNonTransferable -
-
-

- The holder must match the subject only for credentials where the{' '} - - nonTransferable - {' '} - property is true. -

-
-
- Any -
-
-

- The holder is not required to have any kind of relationship to any - credential subject. -

-
-
- FailFast -
-
-

Declares when validation should return if an error occurs.

-
-
- AllErrors -
-
-

Return all errors that occur during validation.

-
-
- FirstError -
-
-

Return after the first error occurs.

-
-
- KeyType -
-
-
- MethodRelationship -
-
-
- -## Functions - -
-
- start() -
-
-

Initializes the console error panic hook for better error messages

-
-
- - - -## Account - -An account manages one identity. - -It handles private keys, writing to storage and -publishing to the Tangle. - -**Kind**: global class - -- [Account](#Account) - - [.attachMethodRelationships(options)](#Account+attachMethodRelationships) ⇒ Promise.<void> - - [.createMethod(options)](#Account+createMethod) ⇒ Promise.<void> - - [.detachMethodRelationships(options)](#Account+detachMethodRelationships) ⇒ Promise.<void> - - [.did()](#Account+did) ⇒ [DID](#DID) - - [.autopublish()](#Account+autopublish) ⇒ boolean - - [.autosave()](#Account+autosave) ⇒ [AutoSave](#AutoSave) - - [.document()](#Account+document) ⇒ [Document](#Document) - - [.resolveIdentity()](#Account+resolveIdentity) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - - [.deleteIdentity()](#Account+deleteIdentity) ⇒ Promise.<void> - - [.publish(publish_options)](#Account+publish) ⇒ Promise.<void> - - [.createSignedCredential(fragment, credential, options)](#Account+createSignedCredential) ⇒ [Promise.<Credential>](#Credential) - - [.createSignedDocument(fragment, document, options)](#Account+createSignedDocument) ⇒ [Promise.<Document>](#Document) - - [.createSignedPresentation(fragment, presentation, options)](#Account+createSignedPresentation) ⇒ [Promise.<Presentation>](#Presentation) - - [.createSignedData(fragment, data, options)](#Account+createSignedData) ⇒ Promise.<any> - - [.updateDocumentUnchecked(document)](#Account+updateDocumentUnchecked) ⇒ Promise.<void> - - [.fetchDocument()](#Account+fetchDocument) ⇒ Promise.<void> - - [.revokeCredentials(fragment, credentialIndices)](#Account+revokeCredentials) ⇒ Promise.<void> - - [.unrevokeCredentials(fragment, credentialIndices)](#Account+unrevokeCredentials) ⇒ Promise.<void> - - [.encryptData(plaintext, associated_data, encryption_algorithm, cek_algorithm, public_key)](#Account+encryptData) ⇒ [Promise.<EncryptedData>](#EncryptedData) - - [.decryptData(data, encryption_algorithm, cek_algorithm, fragment)](#Account+decryptData) ⇒ Promise.<Uint8Array> - - [.setAlsoKnownAs(options)](#Account+setAlsoKnownAs) ⇒ Promise.<void> - - [.deleteMethod(options)](#Account+deleteMethod) ⇒ Promise.<void> - - [.deleteService(options)](#Account+deleteService) ⇒ Promise.<void> - - [.setController(options)](#Account+setController) ⇒ Promise.<void> - - [.createService(options)](#Account+createService) ⇒ Promise.<void> - - - -### account.attachMethodRelationships(options) ⇒ Promise.<void> - -Attach one or more verification relationships to a method. - -Note: the method must exist and be in the set of verification methods; -it cannot be an embedded method. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | -------------------------------------------- | -| options | AttachMethodRelationshipOptions | - - - -### account.createMethod(options) ⇒ Promise.<void> - -Adds a new verification method to the DID document. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | -------------------------------- | -| options | CreateMethodOptions | - - - -### account.detachMethodRelationships(options) ⇒ Promise.<void> - -Detaches the given relationship from the given method, if the method exists. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | -------------------------------------------- | -| options | DetachMethodRelationshipOptions | - - - -### account.did() ⇒ [DID](#DID) - -Returns the [DID](#DID) of the managed identity. - -**Kind**: instance method of [Account](#Account) - - - -### account.autopublish() ⇒ boolean - -Returns whether auto-publish is enabled. - -**Kind**: instance method of [Account](#Account) - - - -### account.autosave() ⇒ [AutoSave](#AutoSave) - -Returns the auto-save configuration value. - -**Kind**: instance method of [Account](#Account) - - - -### account.document() ⇒ [Document](#Document) - -Returns a copy of the document managed by the `Account`. - -Note: the returned document only has a valid signature after publishing an integration chain update. -In general, for use cases where the signature is required, it is advisable to resolve the -document from the Tangle. - -**Kind**: instance method of [Account](#Account) - - - -### account.resolveIdentity() ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - -Resolves the DID Document associated with this `Account` from the Tangle. - -**Kind**: instance method of [Account](#Account) - - - -### account.deleteIdentity() ⇒ Promise.<void> - -Removes the identity from the local storage entirely. - -Note: This will remove all associated document updates and key material - recovery is NOT POSSIBLE! - -**Kind**: instance method of [Account](#Account) - - - -### account.publish(publish_options) ⇒ Promise.<void> - -Push all unpublished changes to the tangle in a single message. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| --------------- | ----------------------------------------------------- | -| publish_options | PublishOptions \| undefined | - - - -### account.createSignedCredential(fragment, credential, options) ⇒ [Promise.<Credential>](#Credential) - -Signs a [Credential](#Credential) with the key specified by `fragment`. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ---------- | ------------------------------------------ | -| fragment | string | -| credential | [Credential](#Credential) | -| options | [ProofOptions](#ProofOptions) | - - - -### account.createSignedDocument(fragment, document, options) ⇒ [Promise.<Document>](#Document) - -Signs a [Document](#Document) with the key specified by `fragment`. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| -------- | ------------------------------------------ | -| fragment | string | -| document | [Document](#Document) | -| options | [ProofOptions](#ProofOptions) | - - - -### account.createSignedPresentation(fragment, presentation, options) ⇒ [Promise.<Presentation>](#Presentation) - -Signs a [Presentation](#Presentation) the key specified by `fragment`. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------------ | ------------------------------------------ | -| fragment | string | -| presentation | [Presentation](#Presentation) | -| options | [ProofOptions](#ProofOptions) | - - - -### account.createSignedData(fragment, data, options) ⇒ Promise.<any> - -Signs arbitrary `data` with the key specified by `fragment`. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| -------- | ------------------------------------------ | -| fragment | string | -| data | any | -| options | [ProofOptions](#ProofOptions) | - - - -### account.updateDocumentUnchecked(document) ⇒ Promise.<void> - -Overwrites the [Document](#Document) this account manages, **without doing any validation**. - -### WARNING - -This method is dangerous and can easily corrupt the internal state, -potentially making the identity unusable. Only call this if you fully -understand the implications! - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| -------- | ---------------------------------- | -| document | [Document](#Document) | - - - -### account.fetchDocument() ⇒ Promise.<void> - -Fetches the latest changes from the tangle and **overwrites** the local document. - -If a DID is managed from distributed accounts, this should be called before making changes -to the identity, to avoid publishing updates that would be ignored. - -**Kind**: instance method of [Account](#Account) - - - -### account.revokeCredentials(fragment, credentialIndices) ⇒ Promise.<void> - -If the document has a `RevocationBitmap` service identified by `fragment`, -revoke all credentials with a `revocationBitmapIndex` in `credentialIndices`. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ----------------- | -------------------------------------------------------- | -| fragment | string | -| credentialIndices | number \| Array.<number> | - - - -### account.unrevokeCredentials(fragment, credentialIndices) ⇒ Promise.<void> - -If the document has a `RevocationBitmap` service identified by `fragment`, -unrevoke all credentials with a `revocationBitmapIndex` in `credentialIndices`. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ----------------- | -------------------------------------------------------- | -| fragment | string | -| credentialIndices | number \| Array.<number> | - - - -### account.encryptData(plaintext, associated_data, encryption_algorithm, cek_algorithm, public_key) ⇒ [Promise.<EncryptedData>](#EncryptedData) - -Encrypts the given `plaintext` with the specified `encryption_algorithm` and `cek_algorithm`. - -Returns an [`EncryptedData`] instance. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| -------------------- | -------------------------------------------------------- | -| plaintext | Uint8Array | -| associated_data | Uint8Array | -| encryption_algorithm | [EncryptionAlgorithm](#EncryptionAlgorithm) | -| cek_algorithm | [CekAlgorithm](#CekAlgorithm) | -| public_key | Uint8Array | - - - -### account.decryptData(data, encryption_algorithm, cek_algorithm, fragment) ⇒ Promise.<Uint8Array> - -Decrypts the given `data` with the key identified by `fragment` using the given `encryption_algorithm` and -`cek_algorithm`. - -Returns the decrypted text. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| -------------------- | -------------------------------------------------------- | -| data | [EncryptedData](#EncryptedData) | -| encryption_algorithm | [EncryptionAlgorithm](#EncryptionAlgorithm) | -| cek_algorithm | [CekAlgorithm](#CekAlgorithm) | -| fragment | string | - - - -### account.setAlsoKnownAs(options) ⇒ Promise.<void> - -Sets the `alsoKnownAs` property in the DID document. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | ---------------------------------- | -| options | SetAlsoKnownAsOptions | - - - -### account.deleteMethod(options) ⇒ Promise.<void> - -Deletes a verification method if the method exists. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | -------------------------------- | -| options | DeleteMethodOptions | - - - -### account.deleteService(options) ⇒ Promise.<void> - -Deletes a Service if it exists. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | --------------------------------- | -| options | DeleteServiceOptions | - - - -### account.setController(options) ⇒ Promise.<void> - -Sets the controllers of the DID document. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | --------------------------------- | -| options | SetControllerOptions | - - - -### account.createService(options) ⇒ Promise.<void> - -Adds a new Service to the DID Document. - -**Kind**: instance method of [Account](#Account) - -| Param | Type | -| ------- | --------------------------------- | -| options | CreateServiceOptions | - - - -## AccountBuilder - -An [`Account`] builder for easy account configuration. - -To reduce memory usage, accounts created from the same builder share the same `Storage` -used to store identities, and the same [Client](#Client) used to publish identities to the Tangle. - -The configuration on the other hand is cloned, and therefore unique for each built account. -This means a builder can be reconfigured in-between account creations, without affecting -the configuration of previously built accounts. - -**Kind**: global class - -- [AccountBuilder](#AccountBuilder) - - [new AccountBuilder(options)](#new_AccountBuilder_new) - - [.loadIdentity(did)](#AccountBuilder+loadIdentity) ⇒ [Promise.<Account>](#Account) - - [.createIdentity(identity_setup)](#AccountBuilder+createIdentity) ⇒ [Promise.<Account>](#Account) - - - -### new AccountBuilder(options) - -Creates a new `AccountBuilder`. - -| Param | Type | -| ------- | ------------------------------------------------------------ | -| options | AccountBuilderOptions \| undefined | - - - -### accountBuilder.loadIdentity(did) ⇒ [Promise.<Account>](#Account) - -Loads an existing identity with the specified `did` using the current builder configuration. -The identity must exist in the configured `Storage`. - -**Kind**: instance method of [AccountBuilder](#AccountBuilder) - -| Param | Type | -| ----- | ------------------------ | -| did | [DID](#DID) | - - - -### accountBuilder.createIdentity(identity_setup) ⇒ [Promise.<Account>](#Account) - -Creates a new identity based on the builder configuration and returns -an [Account](#Account) object to manage it. - -The identity is stored locally in the `Storage`. The DID network is automatically determined -by the [Client](#Client) used to publish it. - -**Kind**: instance method of [AccountBuilder](#AccountBuilder) - -| Param | Type | -| -------------- | ---------------------------------------------------- | -| identity_setup | IdentitySetup \| undefined | - - - -## AgreementInfo - -Agreement information used as the input for the concat KDF. - -**Kind**: global class - -- [AgreementInfo](#AgreementInfo) - - [new AgreementInfo(apu, apv, pub_info, priv_info)](#new_AgreementInfo_new) - - _instance_ - - [.apu()](#AgreementInfo+apu) ⇒ Uint8Array - - [.apv()](#AgreementInfo+apv) ⇒ Uint8Array - - [.pubInfo()](#AgreementInfo+pubInfo) ⇒ Uint8Array - - [.privInfo()](#AgreementInfo+privInfo) ⇒ Uint8Array - - [.toJSON()](#AgreementInfo+toJSON) ⇒ any - - _static_ - - [.fromJSON(json_value)](#AgreementInfo.fromJSON) ⇒ [AgreementInfo](#AgreementInfo) - - - -### new AgreementInfo(apu, apv, pub_info, priv_info) - -Creates an `AgreementInfo` Object. - -| Param | Type | -| --------- | ----------------------- | -| apu | Uint8Array | -| apv | Uint8Array | -| pub_info | Uint8Array | -| priv_info | Uint8Array | - - - -### agreementInfo.apu() ⇒ Uint8Array - -Returns a copy of `apu' - -**Kind**: instance method of [AgreementInfo](#AgreementInfo) - - - -### agreementInfo.apv() ⇒ Uint8Array - -Returns a copy of `apv' - -**Kind**: instance method of [AgreementInfo](#AgreementInfo) - - - -### agreementInfo.pubInfo() ⇒ Uint8Array - -Returns a copy of `pubInfo' - -**Kind**: instance method of [AgreementInfo](#AgreementInfo) - - - -### agreementInfo.privInfo() ⇒ Uint8Array - -Returns a copy of `privInfo' - -**Kind**: instance method of [AgreementInfo](#AgreementInfo) - - - -### agreementInfo.toJSON() ⇒ any - -Serializes `AgreementInfo` as a JSON object. - -**Kind**: instance method of [AgreementInfo](#AgreementInfo) - - - -### AgreementInfo.fromJSON(json_value) ⇒ [AgreementInfo](#AgreementInfo) - -Deserializes `AgreementInfo` from a JSON object. - -**Kind**: static method of [AgreementInfo](#AgreementInfo) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## AutoSave - -**Kind**: global class - -- [AutoSave](#AutoSave) - - _instance_ - - [.toJSON()](#AutoSave+toJSON) ⇒ any - - _static_ - - [.never()](#AutoSave.never) ⇒ [AutoSave](#AutoSave) - - [.every()](#AutoSave.every) ⇒ [AutoSave](#AutoSave) - - [.batch(number_of_actions)](#AutoSave.batch) ⇒ [AutoSave](#AutoSave) - - [.fromJSON(json_value)](#AutoSave.fromJSON) ⇒ [AutoSave](#AutoSave) - - - -### autoSave.toJSON() ⇒ any - -Serializes `AutoSave` as a JSON object. - -**Kind**: instance method of [AutoSave](#AutoSave) - - - -### AutoSave.never() ⇒ [AutoSave](#AutoSave) - -Never save. - -**Kind**: static method of [AutoSave](#AutoSave) - - - -### AutoSave.every() ⇒ [AutoSave](#AutoSave) - -Save after every action. - -**Kind**: static method of [AutoSave](#AutoSave) - - - -### AutoSave.batch(number_of_actions) ⇒ [AutoSave](#AutoSave) - -Save after every N actions. - -**Kind**: static method of [AutoSave](#AutoSave) - -| Param | Type | -| ----------------- | ------------------- | -| number_of_actions | number | - - - -### AutoSave.fromJSON(json_value) ⇒ [AutoSave](#AutoSave) - -Deserializes `AutoSave` from a JSON object. - -**Kind**: static method of [AutoSave](#AutoSave) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## CekAlgorithm - -Supported algorithms used to determine and potentially encrypt the content encryption key (CEK). - -**Kind**: global class - -- [CekAlgorithm](#CekAlgorithm) - - _instance_ - - [.toJSON()](#CekAlgorithm+toJSON) ⇒ any - - _static_ - - [.EcdhEs(agreement)](#CekAlgorithm.EcdhEs) ⇒ [CekAlgorithm](#CekAlgorithm) - - [.EcdhEsA256Kw(agreement)](#CekAlgorithm.EcdhEsA256Kw) ⇒ [CekAlgorithm](#CekAlgorithm) - - [.fromJSON(json_value)](#CekAlgorithm.fromJSON) ⇒ [CekAlgorithm](#CekAlgorithm) - - - -### cekAlgorithm.toJSON() ⇒ any - -Serializes `CekAlgorithm` as a JSON object. - -**Kind**: instance method of [CekAlgorithm](#CekAlgorithm) - - - -### CekAlgorithm.EcdhEs(agreement) ⇒ [CekAlgorithm](#CekAlgorithm) - -Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF. - -**Kind**: static method of [CekAlgorithm](#CekAlgorithm) - -| Param | Type | -| --------- | -------------------------------------------- | -| agreement | [AgreementInfo](#AgreementInfo) | - - - -### CekAlgorithm.EcdhEsA256Kw(agreement) ⇒ [CekAlgorithm](#CekAlgorithm) - -Elliptic Curve Diffie-Hellman Ephemeral Static key agreement using Concat KDF. - -**Kind**: static method of [CekAlgorithm](#CekAlgorithm) - -| Param | Type | -| --------- | -------------------------------------------- | -| agreement | [AgreementInfo](#AgreementInfo) | - - - -### CekAlgorithm.fromJSON(json_value) ⇒ [CekAlgorithm](#CekAlgorithm) - -Deserializes `CekAlgorithm` from a JSON object. - -**Kind**: static method of [CekAlgorithm](#CekAlgorithm) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## ChainState - -**Kind**: global class - -- [ChainState](#ChainState) - - _instance_ - - [.toJSON()](#ChainState+toJSON) ⇒ any - - _static_ - - [.fromJSON(json_value)](#ChainState.fromJSON) ⇒ [ChainState](#ChainState) - - - -### chainState.toJSON() ⇒ any - -Serializes a `ChainState` object as a JSON object. - -**Kind**: instance method of [ChainState](#ChainState) - - - -### ChainState.fromJSON(json_value) ⇒ [ChainState](#ChainState) - -Deserializes a JSON object as `ChainState`. - -**Kind**: static method of [ChainState](#ChainState) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## Client - -**Kind**: global class - -- [Client](#Client) - - [new Client()](#new_Client_new) - - _instance_ - - [.network()](#Client+network) ⇒ [Network](#Network) - - [.publishDocument(document)](#Client+publishDocument) ⇒ [Promise.<Receipt>](#Receipt) - - ~~[.publishDiff(message_id, diff)](#Client+publishDiff) ⇒ [Promise.<Receipt>](#Receipt)~~ - - [.publishJSON(index, data)](#Client+publishJSON) ⇒ [Promise.<Receipt>](#Receipt) - - [.publishJsonWithRetry(index, data, interval, max_attempts)](#Client+publishJsonWithRetry) ⇒ Promise.<any> - - [.isMessageIncluded(messageId)](#Client+isMessageIncluded) ⇒ Promise.<boolean> - - [.resolve(did)](#Client+resolve) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - - [.resolveHistory(did)](#Client+resolveHistory) ⇒ [Promise.<DocumentHistory>](#DocumentHistory) - - ~~[.resolveDiffHistory(document)](#Client+resolveDiffHistory) ⇒ [Promise.<DiffChainHistory>](#DiffChainHistory)~~ - - _static_ - - [.fromConfig(config)](#Client.fromConfig) ⇒ [Promise.<Client>](#Client) - - - -### new Client() - -Creates a new `Client` with default settings. - - - -### client.network() ⇒ [Network](#Network) - -Returns the `Client` Tangle network. - -**Kind**: instance method of [Client](#Client) - - - -### client.publishDocument(document) ⇒ [Promise.<Receipt>](#Receipt) - -Publishes a [Document](#Document) to the Tangle. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| -------- | ---------------------------------- | -| document | [Document](#Document) | - - - -### ~~client.publishDiff(message_id, diff) ⇒ [Promise.<Receipt>](#Receipt)~~ - -**_Deprecated_** - -Publishes a `DiffMessage` to the Tangle. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| ---------- | ---------------------------------------- | -| message_id | string | -| diff | [DiffMessage](#DiffMessage) | - - - -### client.publishJSON(index, data) ⇒ [Promise.<Receipt>](#Receipt) - -Publishes arbitrary JSON data to the specified index on the Tangle. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| ----- | ------------------- | -| index | string | -| data | any | - - - -### client.publishJsonWithRetry(index, data, interval, max_attempts) ⇒ Promise.<any> - -Publishes arbitrary JSON data to the specified index on the Tangle. -Retries (promotes or reattaches) the message until it’s included (referenced by a milestone). -Default interval is 5 seconds and max attempts is 40. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| ------------ | --------------------------------------------- | -| index | string | -| data | any | -| interval | number \| undefined | -| max_attempts | number \| undefined | - - - -### client.isMessageIncluded(messageId) ⇒ Promise.<boolean> - -Checks if a message is confirmed by a milestone. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| --------- | ------------------- | -| messageId | string | - - - -### client.resolve(did) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - -Fetch the DID document specified by the given `DID`. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| ----- | ----------------------------------------------- | -| did | [DID](#DID) \| string | - - - -### client.resolveHistory(did) ⇒ [Promise.<DocumentHistory>](#DocumentHistory) - -Returns the message history of the given DID. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| ----- | ----------------------------------------------- | -| did | [DID](#DID) \| string | - - - -### ~~client.resolveDiffHistory(document) ⇒ [Promise.<DiffChainHistory>](#DiffChainHistory)~~ - -**_Deprecated_** - -Returns the `DiffChainHistory` of a diff chain starting from a document on the -integration chain. - -NOTE: the document must have been published to the tangle and have a valid message id and -capability invocation method. - -**Kind**: instance method of [Client](#Client) - -| Param | Type | -| -------- | -------------------------------------------------- | -| document | [ResolvedDocument](#ResolvedDocument) | - - - -### Client.fromConfig(config) ⇒ [Promise.<Client>](#Client) - -Creates a new `Client` with the given settings. - -**Kind**: static method of [Client](#Client) - -| Param | Type | -| ------ | -------------------------- | -| config | IClientConfig | - - - -## Credential - -**Kind**: global class - -- [Credential](#Credential) - - [new Credential(values)](#new_Credential_new) - - _instance_ - - [.context()](#Credential+context) ⇒ Array.<(string\|Record.<string, any>)> - - [.id()](#Credential+id) ⇒ string \| undefined - - [.type()](#Credential+type) ⇒ Array.<string> - - [.credentialSubject()](#Credential+credentialSubject) ⇒ Array.<Subject> - - [.issuer()](#Credential+issuer) ⇒ string \| Issuer - - [.issuanceDate()](#Credential+issuanceDate) ⇒ [Timestamp](#Timestamp) - - [.expirationDate()](#Credential+expirationDate) ⇒ [Timestamp](#Timestamp) \| undefined - - [.credentialStatus()](#Credential+credentialStatus) ⇒ Array.<Status> - - [.credentialSchema()](#Credential+credentialSchema) ⇒ Array.<Schema> - - [.refreshService()](#Credential+refreshService) ⇒ Array.<RefreshService> - - [.termsOfUse()](#Credential+termsOfUse) ⇒ Array.<Policy> - - [.evidence()](#Credential+evidence) ⇒ Array.<Evidence> - - [.nonTransferable()](#Credential+nonTransferable) ⇒ boolean \| undefined - - [.proof()](#Credential+proof) ⇒ [Proof](#Proof) \| undefined - - [.properties()](#Credential+properties) ⇒ Map.<string, any> - - [.toJSON()](#Credential+toJSON) ⇒ any - - [.clone()](#Credential+clone) ⇒ [Credential](#Credential) - - _static_ - - [.BaseContext()](#Credential.BaseContext) ⇒ string - - [.BaseType()](#Credential.BaseType) ⇒ string - - [.fromJSON(json)](#Credential.fromJSON) ⇒ [Credential](#Credential) - - - -### new Credential(values) - -Constructs a new `Credential`. - -| Param | Type | -| ------ | ------------------------ | -| values | ICredential | - - - -### credential.context() ⇒ Array.<(string\|Record.<string, any>)> - -Returns a copy of the JSON-LD context(s) applicable to the `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.id() ⇒ string \| undefined - -Returns a copy of the unique `URI` identifying the `Credential` . - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.type() ⇒ Array.<string> - -Returns a copy of the URIs defining the type of the `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.credentialSubject() ⇒ Array.<Subject> - -Returns a copy of the `Credential` subject(s). - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.issuer() ⇒ string \| Issuer - -Returns a copy of the issuer of the `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.issuanceDate() ⇒ [Timestamp](#Timestamp) - -Returns a copy of the timestamp of when the `Credential` becomes valid. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.expirationDate() ⇒ [Timestamp](#Timestamp) \| undefined - -Returns a copy of the timestamp of when the `Credential` should no longer be considered valid. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.credentialStatus() ⇒ Array.<Status> - -Returns a copy of the information used to determine the current status of the `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.credentialSchema() ⇒ Array.<Schema> - -Returns a copy of the information used to assist in the enforcement of a specific `Credential` structure. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.refreshService() ⇒ Array.<RefreshService> - -Returns a copy of the service(s) used to refresh an expired `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.termsOfUse() ⇒ Array.<Policy> - -Returns a copy of the terms-of-use specified by the `Credential` issuer. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.evidence() ⇒ Array.<Evidence> - -Returns a copy of the human-readable evidence used to support the claims within the `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.nonTransferable() ⇒ boolean \| undefined - -Returns whether or not the `Credential` must only be contained within a [Presentation](#Presentation) -with a proof issued from the `Credential` subject. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.proof() ⇒ [Proof](#Proof) \| undefined - -Returns a copy of the proof used to verify the `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.properties() ⇒ Map.<string, any> - -Returns a copy of the miscellaneous properties on the `Credential`. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.toJSON() ⇒ any - -Serializes a `Credential` to a JSON object. - -**Kind**: instance method of [Credential](#Credential) - - - -### credential.clone() ⇒ [Credential](#Credential) - -Deep clones the object. - -**Kind**: instance method of [Credential](#Credential) - - - -### Credential.BaseContext() ⇒ string - -Returns the base JSON-LD context. - -**Kind**: static method of [Credential](#Credential) - - - -### Credential.BaseType() ⇒ string - -Returns the base type. - -**Kind**: static method of [Credential](#Credential) - - - -### Credential.fromJSON(json) ⇒ [Credential](#Credential) - -Deserializes a `Credential` from a JSON object. - -**Kind**: static method of [Credential](#Credential) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## CredentialValidationOptions - -Options to declare validation criteria when validating credentials. - -**Kind**: global class - -- [CredentialValidationOptions](#CredentialValidationOptions) - - [new CredentialValidationOptions(options)](#new_CredentialValidationOptions_new) - - _instance_ - - [.toJSON()](#CredentialValidationOptions+toJSON) ⇒ any - - [.clone()](#CredentialValidationOptions+clone) ⇒ [CredentialValidationOptions](#CredentialValidationOptions) - - _static_ - - [.default()](#CredentialValidationOptions.default) ⇒ [CredentialValidationOptions](#CredentialValidationOptions) - - [.fromJSON(json)](#CredentialValidationOptions.fromJSON) ⇒ [CredentialValidationOptions](#CredentialValidationOptions) - - - -### new CredentialValidationOptions(options) - -Creates a new `CredentialValidationOptions` from the given fields. - -Throws an error if any of the options are invalid. - -| Param | Type | -| ------- | ----------------------------------------- | -| options | ICredentialValidationOptions | - - - -### credentialValidationOptions.toJSON() ⇒ any - -Serializes a `CredentialValidationOptions` as a JSON object. - -**Kind**: instance method of [CredentialValidationOptions](#CredentialValidationOptions) - - - -### credentialValidationOptions.clone() ⇒ [CredentialValidationOptions](#CredentialValidationOptions) - -Deep clones the object. - -**Kind**: instance method of [CredentialValidationOptions](#CredentialValidationOptions) - - - -### CredentialValidationOptions.default() ⇒ [CredentialValidationOptions](#CredentialValidationOptions) - -Creates a new `CredentialValidationOptions` with defaults. - -**Kind**: static method of [CredentialValidationOptions](#CredentialValidationOptions) - - - -### CredentialValidationOptions.fromJSON(json) ⇒ [CredentialValidationOptions](#CredentialValidationOptions) - -Deserializes a `CredentialValidationOptions` from a JSON object. - -**Kind**: static method of [CredentialValidationOptions](#CredentialValidationOptions) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## CredentialValidator - -**Kind**: global class - -- [CredentialValidator](#CredentialValidator) - - [.validate(credential, issuer, options, fail_fast)](#CredentialValidator.validate) - - [.checkStructure(credential)](#CredentialValidator.checkStructure) - - [.checkExpiresOnOrAfter(credential, timestamp)](#CredentialValidator.checkExpiresOnOrAfter) - - [.checkIssuedOnOrBefore(credential, timestamp)](#CredentialValidator.checkIssuedOnOrBefore) - - [.verifySignature(credential, trusted_issuers, options)](#CredentialValidator.verifySignature) - - [.check_subject_holder_relationship(credential, holder_url, relationship)](#CredentialValidator.check_subject_holder_relationship) - - [.checkStatus(credential, trustedIssuers, statusCheck)](#CredentialValidator.checkStatus) - - - -### CredentialValidator.validate(credential, issuer, options, fail_fast) - -Validates a `Credential`. - -The following properties are validated according to `options`: - -- the issuer's signature, -- the expiration date, -- the issuance date, -- the semantic structure. - -### Warning - -The lack of an error returned from this method is in of itself not enough to conclude that the credential can be -trusted. This section contains more information on additional checks that should be carried out before and after -calling this method. - -#### The state of the issuer's DID Document - -The caller must ensure that `issuer` represents an up-to-date DID Document. The convenience method -`Resolver::resolveCredentialIssuer` can help extract the latest available state of the issuer's DID Document. - -#### Properties that are not validated - -There are many properties defined in [The Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) that are **not** validated, such as: -`credentialStatus`, `type`, `credentialSchema`, `refreshService`, **and more**. -These should be manually checked after validation, according to your requirements. - -### Errors - -An error is returned whenever a validated condition is not satisfied. - -**Kind**: static method of [CredentialValidator](#CredentialValidator) - -| Param | Type | -| ---------- | ---------------------------------------------------------------------------------------- | -| credential | [Credential](#Credential) | -| issuer | [Document](#Document) \| [ResolvedDocument](#ResolvedDocument) | -| options | [CredentialValidationOptions](#CredentialValidationOptions) | -| fail_fast | number | - - - -### CredentialValidator.checkStructure(credential) - -Validates the semantic structure of the `Credential`. - -### Warning - -This does not validate against the credential's schema nor the structure of the subject claims. - -**Kind**: static method of [CredentialValidator](#CredentialValidator) - -| Param | Type | -| ---------- | -------------------------------------- | -| credential | [Credential](#Credential) | - - - -### CredentialValidator.checkExpiresOnOrAfter(credential, timestamp) - -Validate that the credential expires on or after the specified timestamp. - -**Kind**: static method of [CredentialValidator](#CredentialValidator) - -| Param | Type | -| ---------- | -------------------------------------- | -| credential | [Credential](#Credential) | -| timestamp | [Timestamp](#Timestamp) | - - - -### CredentialValidator.checkIssuedOnOrBefore(credential, timestamp) - -Validate that the credential is issued on or before the specified timestamp. - -**Kind**: static method of [CredentialValidator](#CredentialValidator) - -| Param | Type | -| ---------- | -------------------------------------- | -| credential | [Credential](#Credential) | -| timestamp | [Timestamp](#Timestamp) | - - - -### CredentialValidator.verifySignature(credential, trusted_issuers, options) - -Verify the signature using the DID Document of a trusted issuer. - -# Warning - -The caller must ensure that the DID Documents of the trusted issuers are up-to-date. - -### Errors - -This method immediately returns an error if -the credential issuer' url cannot be parsed to a DID belonging to one of the trusted issuers. Otherwise an attempt -to verify the credential's signature will be made and an error is returned upon failure. - -**Kind**: static method of [CredentialValidator](#CredentialValidator) - -| Param | Type | -| --------------- | -------------------------------------------------------------------------------------------------------------------- | -| credential | [Credential](#Credential) | -| trusted_issuers | [Array.<Document>](#Document) \| [Array.<ResolvedDocument>](#ResolvedDocument) | -| options | [VerifierOptions](#VerifierOptions) | - - - -### CredentialValidator.check_subject_holder_relationship(credential, holder_url, relationship) - -Validate that the relationship between the `holder` and the credential subjects is in accordance with -`relationship`. The `holder_url` parameter is expected to be the URL of the holder. - -**Kind**: static method of [CredentialValidator](#CredentialValidator) - -| Param | Type | -| ------------ | -------------------------------------- | -| credential | [Credential](#Credential) | -| holder_url | string | -| relationship | number | - - - -### CredentialValidator.checkStatus(credential, trustedIssuers, statusCheck) - -Checks whether the credential status has been revoked. - -Only supports `BitmapRevocation2022`. - -**Kind**: static method of [CredentialValidator](#CredentialValidator) - -| Param | Type | -| -------------- | -------------------------------------------------------------------------------------------------------------------- | -| credential | [Credential](#Credential) | -| trustedIssuers | [Array.<Document>](#Document) \| [Array.<ResolvedDocument>](#ResolvedDocument) | -| statusCheck | number | - - - -## DID - -**Kind**: global class - -- [DID](#DID) - - [new DID(public_key, network)](#new_DID_new) - - _instance_ - - [.networkName](#DID+networkName) ⇒ string - - [.network()](#DID+network) ⇒ [Network](#Network) - - [.tag()](#DID+tag) ⇒ string - - [.join(segment)](#DID+join) ⇒ [DIDUrl](#DIDUrl) - - [.toUrl()](#DID+toUrl) ⇒ [DIDUrl](#DIDUrl) - - [.intoUrl()](#DID+intoUrl) ⇒ [DIDUrl](#DIDUrl) - - [.toString()](#DID+toString) ⇒ string - - [.toJSON()](#DID+toJSON) ⇒ any - - [.clone()](#DID+clone) ⇒ [DID](#DID) - - _static_ - - [.parse(input)](#DID.parse) ⇒ [DID](#DID) - - [.fromJSON(json_value)](#DID.fromJSON) ⇒ [DID](#DID) - - - -### new DID(public_key, network) - -Creates a new `DID` from a public key. - -| Param | Type | -| ---------- | --------------------------------------------- | -| public_key | Uint8Array | -| network | string \| undefined | - - - -### did.networkName ⇒ string - -Returns the IOTA tangle network of the `DID`. - -**Kind**: instance property of [DID](#DID) - - - -### did.network() ⇒ [Network](#Network) - -Returns the IOTA tangle network of the `DID`. - -**Kind**: instance method of [DID](#DID) - - - -### did.tag() ⇒ string - -Returns a copy of the unique tag of the `DID`. - -**Kind**: instance method of [DID](#DID) - - - -### did.join(segment) ⇒ [DIDUrl](#DIDUrl) - -Construct a new `DIDUrl` by joining with a relative DID Url string. - -**Kind**: instance method of [DID](#DID) - -| Param | Type | -| ------- | ------------------- | -| segment | string | - - - -### did.toUrl() ⇒ [DIDUrl](#DIDUrl) - -Clones the `DID` into a `DIDUrl`. - -**Kind**: instance method of [DID](#DID) - - - -### did.intoUrl() ⇒ [DIDUrl](#DIDUrl) - -Converts the `DID` into a `DIDUrl`. - -**Kind**: instance method of [DID](#DID) - - - -### did.toString() ⇒ string - -Returns the `DID` as a string. - -**Kind**: instance method of [DID](#DID) - - - -### did.toJSON() ⇒ any - -Serializes a `DID` as a JSON object. - -**Kind**: instance method of [DID](#DID) - - - -### did.clone() ⇒ [DID](#DID) - -Deep clones the object. - -**Kind**: instance method of [DID](#DID) - - - -### DID.parse(input) ⇒ [DID](#DID) - -Parses a `DID` from the input string. - -**Kind**: static method of [DID](#DID) - -| Param | Type | -| ----- | ------------------- | -| input | string | - - - -### DID.fromJSON(json_value) ⇒ [DID](#DID) - -Deserializes a JSON object as `DID`. - -**Kind**: static method of [DID](#DID) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## DIDUrl - -**Kind**: global class - -- [DIDUrl](#DIDUrl) - - _instance_ - - [.did()](#DIDUrl+did) ⇒ [DID](#DID) - - [.urlStr()](#DIDUrl+urlStr) ⇒ string - - [.fragment()](#DIDUrl+fragment) ⇒ string \| undefined - - [.setFragment(value)](#DIDUrl+setFragment) - - [.path()](#DIDUrl+path) ⇒ string \| undefined - - [.setPath(value)](#DIDUrl+setPath) - - [.query()](#DIDUrl+query) ⇒ string \| undefined - - [.setQuery(value)](#DIDUrl+setQuery) - - [.join(segment)](#DIDUrl+join) ⇒ [DIDUrl](#DIDUrl) - - [.toString()](#DIDUrl+toString) ⇒ string - - [.toJSON()](#DIDUrl+toJSON) ⇒ any - - [.clone()](#DIDUrl+clone) ⇒ [DIDUrl](#DIDUrl) - - _static_ - - [.parse(input)](#DIDUrl.parse) ⇒ [DIDUrl](#DIDUrl) - - - -### didUrl.did() ⇒ [DID](#DID) - -Return a copy of the `DID` section of the `DIDUrl`. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### didUrl.urlStr() ⇒ string - -Return a copy of the relative DID Url as a string, including only the path, query, and fragment. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### didUrl.fragment() ⇒ string \| undefined - -Returns a copy of the `DIDUrl` method fragment, if any. Excludes the leading '#'. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### didUrl.setFragment(value) - -Sets the `fragment` component of the `DIDUrl`. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - -| Param | Type | -| ----- | --------------------------------------------- | -| value | string \| undefined | - - - -### didUrl.path() ⇒ string \| undefined - -Returns a copy of the `DIDUrl` path. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### didUrl.setPath(value) - -Sets the `path` component of the `DIDUrl`. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - -| Param | Type | -| ----- | --------------------------------------------- | -| value | string \| undefined | - - - -### didUrl.query() ⇒ string \| undefined - -Returns a copy of the `DIDUrl` method query, if any. Excludes the leading '?'. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### didUrl.setQuery(value) - -Sets the `query` component of the `DIDUrl`. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - -| Param | Type | -| ----- | --------------------------------------------- | -| value | string \| undefined | - - - -### didUrl.join(segment) ⇒ [DIDUrl](#DIDUrl) - -Append a string representing a path, query, and/or fragment, returning a new `DIDUrl`. - -Must begin with a valid delimiter character: '/', '?', '#'. Overwrites the existing URL -segment and any following segments in order of path, query, then fragment. - -I.e. - -- joining a path will clear the query and fragment. -- joining a query will clear the fragment. -- joining a fragment will only overwrite the fragment. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - -| Param | Type | -| ------- | ------------------- | -| segment | string | - - - -### didUrl.toString() ⇒ string - -Returns the `DIDUrl` as a string. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### didUrl.toJSON() ⇒ any - -Serializes a `DIDUrl` as a JSON object. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### didUrl.clone() ⇒ [DIDUrl](#DIDUrl) - -Deep clones the object. - -**Kind**: instance method of [DIDUrl](#DIDUrl) - - - -### DIDUrl.parse(input) ⇒ [DIDUrl](#DIDUrl) - -Parses a `DIDUrl` from the input string. - -**Kind**: static method of [DIDUrl](#DIDUrl) - -| Param | Type | -| ----- | ------------------- | -| input | string | - - - -## ~~DiffChainHistory~~ - -**_Deprecated_** - -**Kind**: global class - -- ~~[DiffChainHistory](#DiffChainHistory)~~ - - _instance_ - - [.chainData()](#DiffChainHistory+chainData) ⇒ [Array.<DiffMessage>](#DiffMessage) - - [.spam()](#DiffChainHistory+spam) ⇒ Array.<string> - - [.toJSON()](#DiffChainHistory+toJSON) ⇒ any - - _static_ - - [.fromJSON(json)](#DiffChainHistory.fromJSON) ⇒ [DiffChainHistory](#DiffChainHistory) - - - -### diffChainHistory.chainData() ⇒ [Array.<DiffMessage>](#DiffMessage) - -Returns an `Array` of the diff chain `DiffMessages`. - -NOTE: this clones the field. - -**Kind**: instance method of [DiffChainHistory](#DiffChainHistory) - - - -### diffChainHistory.spam() ⇒ Array.<string> - -Returns an `Array` of `MessageIds` as strings. - -NOTE: this clones the field. - -**Kind**: instance method of [DiffChainHistory](#DiffChainHistory) - - - -### diffChainHistory.toJSON() ⇒ any - -Serializes as a JSON object. - -**Kind**: instance method of [DiffChainHistory](#DiffChainHistory) - - - -### DiffChainHistory.fromJSON(json) ⇒ [DiffChainHistory](#DiffChainHistory) - -Deserializes from a JSON object. - -**Kind**: static method of [DiffChainHistory](#DiffChainHistory) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## ~~DiffMessage~~ - -**_Deprecated_** - -Defines the difference between two DID `Document`s' JSON representations. - -**Kind**: global class - -- ~~[DiffMessage](#DiffMessage)~~ - - _instance_ - - ~~[.id()](#DiffMessage+id) ⇒ [DID](#DID)~~ - - ~~[.did()](#DiffMessage+did) ⇒ [DID](#DID)~~ - - ~~[.diff()](#DiffMessage+diff) ⇒ string~~ - - ~~[.messageId()](#DiffMessage+messageId) ⇒ string~~ - - ~~[.setMessageId(message_id)](#DiffMessage+setMessageId)~~ - - ~~[.previousMessageId()](#DiffMessage+previousMessageId) ⇒ string~~ - - ~~[.setPreviousMessageId(message_id)](#DiffMessage+setPreviousMessageId)~~ - - ~~[.proof()](#DiffMessage+proof) ⇒ [Proof](#Proof) \| undefined~~ - - ~~[.merge(document)](#DiffMessage+merge) ⇒ [Document](#Document)~~ - - ~~[.toJSON()](#DiffMessage+toJSON) ⇒ any~~ - - [.clone()](#DiffMessage+clone) ⇒ [DiffMessage](#DiffMessage) - - _static_ - - ~~[.fromJSON(json)](#DiffMessage.fromJSON) ⇒ [DiffMessage](#DiffMessage)~~ - - - -### ~~diffMessage.id() ⇒ [DID](#DID)~~ - -**_Deprecated_** - -Returns the DID of the associated DID Document. - -NOTE: clones the data. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### ~~diffMessage.did() ⇒ [DID](#DID)~~ - -**_Deprecated_** - -Returns a copy of the DID of the associated DID Document. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### ~~diffMessage.diff() ⇒ string~~ - -**_Deprecated_** - -Returns a copy of the raw contents of the DID Document diff as a JSON string. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### ~~diffMessage.messageId() ⇒ string~~ - -**_Deprecated_** - -Returns a copy of the message_id of the DID Document diff. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### ~~diffMessage.setMessageId(message_id)~~ - -**_Deprecated_** - -Sets the message_id of the DID Document diff. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - -| Param | Type | -| ---------- | ------------------- | -| message_id | string | - - - -### ~~diffMessage.previousMessageId() ⇒ string~~ - -**_Deprecated_** - -Returns a copy of the Tangle message id of the previous DID Document diff. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### ~~diffMessage.setPreviousMessageId(message_id)~~ - -**_Deprecated_** - -Sets the Tangle message id of the previous DID Document diff. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - -| Param | Type | -| ---------- | ------------------- | -| message_id | string | - - - -### ~~diffMessage.proof() ⇒ [Proof](#Proof) \| undefined~~ - -**_Deprecated_** - -Returns a copy of the proof. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### ~~diffMessage.merge(document) ⇒ [Document](#Document)~~ - -**_Deprecated_** - -Returns a new DID Document which is the result of merging `self` -with the given Document. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - -| Param | Type | -| -------- | ---------------------------------- | -| document | [Document](#Document) | - - - -### ~~diffMessage.toJSON() ⇒ any~~ - -**_Deprecated_** - -Serializes a `DiffMessage` as a JSON object. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### diffMessage.clone() ⇒ [DiffMessage](#DiffMessage) - -Deep clones the object. - -**Kind**: instance method of [DiffMessage](#DiffMessage) - - - -### ~~DiffMessage.fromJSON(json) ⇒ [DiffMessage](#DiffMessage)~~ - -**_Deprecated_** - -Deserializes a `DiffMessage` from a JSON object. - -**Kind**: static method of [DiffMessage](#DiffMessage) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## Document - -**Kind**: global class - -- [Document](#Document) - - [new Document(keypair, network, fragment)](#new_Document_new) - - _instance_ - - [.id()](#Document+id) ⇒ [DID](#DID) - - [.setController(controllers)](#Document+setController) - - [.controller()](#Document+controller) ⇒ [Array.<DID>](#DID) - - [.setAlsoKnownAs(urls)](#Document+setAlsoKnownAs) - - [.alsoKnownAs()](#Document+alsoKnownAs) ⇒ Array.<string> - - [.setPropertyUnchecked(key, value)](#Document+setPropertyUnchecked) - - [.properties()](#Document+properties) ⇒ Map.<string, any> - - [.service()](#Document+service) ⇒ [Array.<Service>](#Service) - - [.insertService(service)](#Document+insertService) ⇒ boolean - - [.removeService(did)](#Document+removeService) ⇒ boolean - - [.methods()](#Document+methods) ⇒ [Array.<VerificationMethod>](#VerificationMethod) - - [.insertMethod(method, scope)](#Document+insertMethod) - - [.removeMethod(did)](#Document+removeMethod) - - [.defaultSigningMethod()](#Document+defaultSigningMethod) ⇒ [VerificationMethod](#VerificationMethod) - - [.resolveMethod(query, scope)](#Document+resolveMethod) ⇒ [VerificationMethod](#VerificationMethod) \| undefined - - [.resolveSigningMethod(query)](#Document+resolveSigningMethod) ⇒ [VerificationMethod](#VerificationMethod) - - [.attachMethodRelationship(did_url, relationship)](#Document+attachMethodRelationship) ⇒ boolean - - [.detachMethodRelationship(did_url, relationship)](#Document+detachMethodRelationship) ⇒ boolean - - [.signSelf(key_pair, method_query)](#Document+signSelf) - - [.signDocument(document, key_pair, method_query)](#Document+signDocument) - - [.signCredential(credential, privateKey, methodQuery, options)](#Document+signCredential) ⇒ [Credential](#Credential) - - [.signPresentation(presentation, privateKey, methodQuery, options)](#Document+signPresentation) ⇒ [Presentation](#Presentation) - - [.signData(data, privateKey, methodQuery, options)](#Document+signData) ⇒ any - - [.verifyData(data, options)](#Document+verifyData) ⇒ boolean - - [.verifyDocument(signed)](#Document+verifyDocument) - - ~~[.diff(other, message_id, key, method_query)](#Document+diff) ⇒ [DiffMessage](#DiffMessage)~~ - - ~~[.verifyDiff(diff)](#Document+verifyDiff)~~ - - ~~[.mergeDiff(diff)](#Document+mergeDiff)~~ - - [.integrationIndex()](#Document+integrationIndex) ⇒ string - - [.metadata()](#Document+metadata) ⇒ [DocumentMetadata](#DocumentMetadata) - - [.metadataCreated()](#Document+metadataCreated) ⇒ [Timestamp](#Timestamp) \| undefined - - [.setMetadataCreated(timestamp)](#Document+setMetadataCreated) - - [.metadataUpdated()](#Document+metadataUpdated) ⇒ [Timestamp](#Timestamp) \| undefined - - [.setMetadataUpdated(timestamp)](#Document+setMetadataUpdated) - - [.metadataPreviousMessageId()](#Document+metadataPreviousMessageId) ⇒ string - - [.setMetadataPreviousMessageId(value)](#Document+setMetadataPreviousMessageId) - - [.proof()](#Document+proof) ⇒ [Proof](#Proof) \| undefined - - [.revokeCredentials(fragment, credentialIndices)](#Document+revokeCredentials) - - [.unrevokeCredentials(fragment, credentialIndices)](#Document+unrevokeCredentials) - - [.toJSON()](#Document+toJSON) ⇒ any - - [.clone()](#Document+clone) ⇒ [Document](#Document) - - _static_ - - [.fromVerificationMethod(method)](#Document.fromVerificationMethod) ⇒ [Document](#Document) - - [.isSigningMethodType(method_type)](#Document.isSigningMethodType) ⇒ boolean - - [.verifyRootDocument(document)](#Document.verifyRootDocument) - - ~~[.diffIndex(message_id)](#Document.diffIndex) ⇒ string~~ - - [.fromJSON(json)](#Document.fromJSON) ⇒ [Document](#Document) - - - -### new Document(keypair, network, fragment) - -Creates a new DID Document from the given `KeyPair`, network, and verification method -fragment name. - -The DID Document will be pre-populated with a single verification method -derived from the provided `KeyPair` embedded as a capability invocation -verification relationship. This method will have the DID URL fragment -`#sign-0` by default and can be easily retrieved with `Document::defaultSigningMethod`. - -NOTE: the generated document is unsigned, see `Document::signSelf`. - -Arguments: - -- keypair: the initial verification method is derived from the public key with this keypair. -- network: Tangle network to use for the DID, default `Network::mainnet`. -- fragment: name of the initial verification method, default "sign-0". - -| Param | Type | -| -------- | --------------------------------------------- | -| keypair | [KeyPair](#KeyPair) | -| network | string \| undefined | -| fragment | string \| undefined | - - - -### document.id() ⇒ [DID](#DID) - -Returns a copy of the DID Document `id`. - -**Kind**: instance method of [Document](#Document) - - - -### document.setController(controllers) - -Sets the controllers of the DID Document. - -Note: Duplicates will be ignored. -Use `null` to remove all controllers. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----------- | --------------------------------------------------------------------------------------- | -| controllers | [DID](#DID) \| [Array.<DID>](#DID) \| null | - - - -### document.controller() ⇒ [Array.<DID>](#DID) - -Returns a list of document controllers. - -**Kind**: instance method of [Document](#Document) - - - -### document.setAlsoKnownAs(urls) - -Sets the `alsoKnownAs` property in the DID document. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ----------------------------------------------------------------------------- | -| urls | string \| Array.<string> \| null | - - - -### document.alsoKnownAs() ⇒ Array.<string> - -Returns a set of the document's `alsoKnownAs`. - -**Kind**: instance method of [Document](#Document) - - - -### document.setPropertyUnchecked(key, value) - -Adds a custom property to the DID Document. -If the value is set to `null`, the custom property will be removed. - -### WARNING - -This method can overwrite existing properties like `id` and result in an invalid document. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ------------------- | -| key | string | -| value | any | - - - -### document.properties() ⇒ Map.<string, any> - -Returns a copy of the custom DID Document properties. - -**Kind**: instance method of [Document](#Document) - - - -### document.service() ⇒ [Array.<Service>](#Service) - -Return a set of all [Services](#Service) in the document. - -**Kind**: instance method of [Document](#Document) - - - -### document.insertService(service) ⇒ boolean - -Add a new [Service](#Service) to the document. - -Returns `true` if the service was added. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------- | -------------------------------- | -| service | [Service](#Service) | - - - -### document.removeService(did) ⇒ boolean - -Remove a [Service](#Service) identified by the given [DIDUrl](#DIDUrl) from the document. - -Returns `true` if a service was removed. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ------------------------------ | -| did | [DIDUrl](#DIDUrl) | - - - -### document.methods() ⇒ [Array.<VerificationMethod>](#VerificationMethod) - -Returns a list of all [VerificationMethod](#VerificationMethod) in the DID Document. - -**Kind**: instance method of [Document](#Document) - - - -### document.insertMethod(method, scope) - -Adds a new Verification Method to the DID Document. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------ | ------------------------------------------------------ | -| method | [VerificationMethod](#VerificationMethod) | -| scope | [MethodScope](#MethodScope) | - - - -### document.removeMethod(did) - -Removes all references to the specified Verification Method. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ------------------------------ | -| did | [DIDUrl](#DIDUrl) | - - - -### document.defaultSigningMethod() ⇒ [VerificationMethod](#VerificationMethod) - -Returns a copy of the first `VerificationMethod` with a capability invocation relationship -capable of signing this DID document. - -Throws an error if no signing method is present. - -**Kind**: instance method of [Document](#Document) - - - -### document.resolveMethod(query, scope) ⇒ [VerificationMethod](#VerificationMethod) \| undefined - -Returns a copy of the first `VerificationMethod` with an `id` property -matching the provided `query`. - -Throws an error if the method is not found. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ------------------------------------------------------------------ | -| query | [DIDUrl](#DIDUrl) \| string | -| scope | [MethodScope](#MethodScope) \| undefined | - - - -### document.resolveSigningMethod(query) ⇒ [VerificationMethod](#VerificationMethod) - -Attempts to resolve the given method query into a method capable of signing a document update. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ----------------------------------------------------- | -| query | [DIDUrl](#DIDUrl) \| string | - - - -### document.attachMethodRelationship(did_url, relationship) ⇒ boolean - -Attaches the relationship to the given method, if the method exists. - -Note: The method needs to be in the set of verification methods, -so it cannot be an embedded one. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------------ | ------------------------------ | -| did_url | [DIDUrl](#DIDUrl) | -| relationship | number | - - - -### document.detachMethodRelationship(did_url, relationship) ⇒ boolean - -Detaches the given relationship from the given method, if the method exists. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------------ | ------------------------------ | -| did_url | [DIDUrl](#DIDUrl) | -| relationship | number | - - - -### document.signSelf(key_pair, method_query) - -Signs the DID document with the verification method specified by `method_query`. -The `method_query` may be the full `DIDUrl` of the method or just its fragment, -e.g. "#sign-0". - -NOTE: does not validate whether the private key of the given `key_pair` corresponds to the -verification method. See `Document::verifySelfSigned`. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------------ | ----------------------------------------------------- | -| key_pair | [KeyPair](#KeyPair) | -| method_query | [DIDUrl](#DIDUrl) \| string | - - - -### document.signDocument(document, key_pair, method_query) - -Signs another DID document using the verification method specified by `method_query`. -The `method_query` may be the full `DIDUrl` of the method or just its fragment, -e.g. "#sign-0". - -`Document.signSelf` should be used in general, this throws an error if trying to operate -on the same document. This is intended for signing updates to a document where a sole -capability invocation method is rotated or replaced entirely. - -NOTE: does not validate whether the private key of the given `key_pair` corresponds to the -verification method. See [Document.verifyDocument](#Document+verifyDocument). - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------------ | ----------------------------------------------------- | -| document | [Document](#Document) | -| key_pair | [KeyPair](#KeyPair) | -| method_query | [DIDUrl](#DIDUrl) \| string | - - - -### document.signCredential(credential, privateKey, methodQuery, options) ⇒ [Credential](#Credential) - -Creates a signature for the given `Credential` with the specified DID Document -Verification Method. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----------- | ----------------------------------------------------- | -| credential | [Credential](#Credential) | -| privateKey | Uint8Array | -| methodQuery | [DIDUrl](#DIDUrl) \| string | -| options | [ProofOptions](#ProofOptions) | - - - -### document.signPresentation(presentation, privateKey, methodQuery, options) ⇒ [Presentation](#Presentation) - -Creates a signature for the given `Presentation` with the specified DID Document -Verification Method. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------------ | ----------------------------------------------------- | -| presentation | [Presentation](#Presentation) | -| privateKey | Uint8Array | -| methodQuery | [DIDUrl](#DIDUrl) \| string | -| options | [ProofOptions](#ProofOptions) | - - - -### document.signData(data, privateKey, methodQuery, options) ⇒ any - -Creates a signature for the given `data` with the specified DID Document -Verification Method. - -NOTE: use `signSelf` or `signDocument` for DID Documents. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----------- | ----------------------------------------------------- | -| data | any | -| privateKey | Uint8Array | -| methodQuery | [DIDUrl](#DIDUrl) \| string | -| options | [ProofOptions](#ProofOptions) | - - - -### document.verifyData(data, options) ⇒ boolean - -Verifies the authenticity of `data` using the target verification method. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------- | ------------------------------------------------ | -| data | any | -| options | [VerifierOptions](#VerifierOptions) | - - - -### document.verifyDocument(signed) - -Verifies that the signature on the DID document `signed` was generated by a valid method from -this DID document. - -# Errors - -Fails if: - -- The signature proof section is missing in the `signed` document. -- The method is not found in this document. -- An unsupported verification method is used. -- The signature verification operation fails. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------ | ---------------------------------- | -| signed | [Document](#Document) | - - - -### ~~document.diff(other, message_id, key, method_query) ⇒ [DiffMessage](#DiffMessage)~~ - -**_Deprecated_** - -Generate a `DiffMessage` between two DID Documents and sign it using the specified -`key` and `method`. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ------------ | ----------------------------------------------------- | -| other | [Document](#Document) | -| message_id | string | -| key | [KeyPair](#KeyPair) | -| method_query | [DIDUrl](#DIDUrl) \| string | - - - -### ~~document.verifyDiff(diff)~~ - -**_Deprecated_** - -Verifies the signature of the `diff` was created using a capability invocation method -in this DID Document. - -# Errors - -Fails if an unsupported verification method is used or the verification operation fails. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ---------------------------------------- | -| diff | [DiffMessage](#DiffMessage) | - - - -### ~~document.mergeDiff(diff)~~ - -**_Deprecated_** - -Verifies a `DiffMessage` signature and attempts to merge the changes into `self`. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ---------------------------------------- | -| diff | [DiffMessage](#DiffMessage) | - - - -### document.integrationIndex() ⇒ string - -Returns the Tangle index of the integration chain for this DID. - -This is simply the tag segment of the `DID`. -E.g. -For a document with DID: did:iota:1234567890abcdefghijklmnopqrstuvxyzABCDEFGHI, -`doc.integration_index()` == "1234567890abcdefghijklmnopqrstuvxyzABCDEFGHI" - -**Kind**: instance method of [Document](#Document) - - - -### document.metadata() ⇒ [DocumentMetadata](#DocumentMetadata) - -Returns a copy of the metadata associated with this document. - -NOTE: Copies all the metadata. See also `metadataCreated`, `metadataUpdated`, -`metadataPreviousMessageId`, `metadataProof` if only a subset of the metadata required. - -**Kind**: instance method of [Document](#Document) - - - -### document.metadataCreated() ⇒ [Timestamp](#Timestamp) \| undefined - -Returns a copy of the timestamp of when the DID document was created. - -**Kind**: instance method of [Document](#Document) - - - -### document.setMetadataCreated(timestamp) - -Sets the timestamp of when the DID document was created. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| --------- | -------------------------------------------------------------- | -| timestamp | [Timestamp](#Timestamp) \| undefined | - - - -### document.metadataUpdated() ⇒ [Timestamp](#Timestamp) \| undefined - -Returns a copy of the timestamp of the last DID document update. - -**Kind**: instance method of [Document](#Document) - - - -### document.setMetadataUpdated(timestamp) - -Sets the timestamp of the last DID document update. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| --------- | -------------------------------------------------------------- | -| timestamp | [Timestamp](#Timestamp) \| undefined | - - - -### document.metadataPreviousMessageId() ⇒ string - -Returns a copy of the previous integration chain message id. - -**Kind**: instance method of [Document](#Document) - - - -### document.setMetadataPreviousMessageId(value) - -Sets the previous integration chain message id. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----- | ------------------- | -| value | string | - - - -### document.proof() ⇒ [Proof](#Proof) \| undefined - -Returns a copy of the proof. - -**Kind**: instance method of [Document](#Document) - - - -### document.revokeCredentials(fragment, credentialIndices) - -If the document has a `RevocationBitmap` service identified by `fragment`, -revoke all credentials with a revocationBitmapIndex in `credentialIndices`. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----------------- | -------------------------------------------------------- | -| fragment | string | -| credentialIndices | number \| Array.<number> | - - - -### document.unrevokeCredentials(fragment, credentialIndices) - -If the document has a `RevocationBitmap` service identified by `fragment`, -unrevoke all credentials with a revocationBitmapIndex in `credentialIndices`. - -**Kind**: instance method of [Document](#Document) - -| Param | Type | -| ----------------- | -------------------------------------------------------- | -| fragment | string | -| credentialIndices | number \| Array.<number> | - - - -### document.toJSON() ⇒ any - -Serializes a `Document` as a JSON object. - -**Kind**: instance method of [Document](#Document) - - - -### document.clone() ⇒ [Document](#Document) - -Deep clones the object. - -**Kind**: instance method of [Document](#Document) - - - -### Document.fromVerificationMethod(method) ⇒ [Document](#Document) - -Creates a new DID Document from the given `VerificationMethod`. - -NOTE: the generated document is unsigned, see `Document::signSelf`. - -**Kind**: static method of [Document](#Document) - -| Param | Type | -| ------ | ------------------------------------------------------ | -| method | [VerificationMethod](#VerificationMethod) | - - - -### Document.isSigningMethodType(method_type) ⇒ boolean - -Returns whether the given [MethodType](#MethodType) can be used to sign document updates. - -**Kind**: static method of [Document](#Document) - -| Param | Type | -| ----------- | -------------------------------------- | -| method_type | [MethodType](#MethodType) | - - - -### Document.verifyRootDocument(document) - -Verifies whether `document` is a valid root DID document according to the IOTA DID method -specification. - -It must be signed using a verification method with a public key whose BLAKE2b-256 hash matches -the DID tag. - -**Kind**: static method of [Document](#Document) - -| Param | Type | -| -------- | ---------------------------------- | -| document | [Document](#Document) | - - - -### ~~Document.diffIndex(message_id) ⇒ string~~ - -**_Deprecated_** - -Returns the Tangle index of the DID diff chain. This should only be called on documents -published on the integration chain. - -This is the Base58-btc encoded SHA-256 digest of the hex-encoded message id. - -**Kind**: static method of [Document](#Document) - -| Param | Type | -| ---------- | ------------------- | -| message_id | string | - - - -### Document.fromJSON(json) ⇒ [Document](#Document) - -Deserializes a `Document` from a JSON object. - -**Kind**: static method of [Document](#Document) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## DocumentHistory - -A DID Document's history and current state. - -**Kind**: global class - -- [DocumentHistory](#DocumentHistory) - - _instance_ - - [.integrationChainData()](#DocumentHistory+integrationChainData) ⇒ [Array.<ResolvedDocument>](#ResolvedDocument) - - [.integrationChainSpam()](#DocumentHistory+integrationChainSpam) ⇒ Array.<string> - - ~~[.diffChainData()](#DocumentHistory+diffChainData) ⇒ [Array.<DiffMessage>](#DiffMessage)~~ - - ~~[.diffChainSpam()](#DocumentHistory+diffChainSpam) ⇒ Array.<string>~~ - - [.toJSON()](#DocumentHistory+toJSON) ⇒ any - - [.clone()](#DocumentHistory+clone) ⇒ [DocumentHistory](#DocumentHistory) - - _static_ - - [.fromJSON(json)](#DocumentHistory.fromJSON) ⇒ [DocumentHistory](#DocumentHistory) - - - -### documentHistory.integrationChainData() ⇒ [Array.<ResolvedDocument>](#ResolvedDocument) - -Returns an `Array` of integration chain `Documents`. - -NOTE: clones the data. - -**Kind**: instance method of [DocumentHistory](#DocumentHistory) - - - -### documentHistory.integrationChainSpam() ⇒ Array.<string> - -Returns an `Array` of message id strings for "spam" messages on the same index -as the integration chain. - -NOTE: clones the data. - -**Kind**: instance method of [DocumentHistory](#DocumentHistory) - - - -### ~~documentHistory.diffChainData() ⇒ [Array.<DiffMessage>](#DiffMessage)~~ - -**_Deprecated_** - -Returns an `Array` of diff chain `DiffMessages`. - -NOTE: clones the data. - -**Kind**: instance method of [DocumentHistory](#DocumentHistory) - - - -### ~~documentHistory.diffChainSpam() ⇒ Array.<string>~~ - -**_Deprecated_** - -Returns an `Array` of message id strings for "spam" messages on the same index -as the diff chain. - -NOTE: clones the data. - -**Kind**: instance method of [DocumentHistory](#DocumentHistory) - - - -### documentHistory.toJSON() ⇒ any - -Serializes `DocumentHistory` as a JSON object. - -**Kind**: instance method of [DocumentHistory](#DocumentHistory) - - - -### documentHistory.clone() ⇒ [DocumentHistory](#DocumentHistory) - -Deep clones the object. - -**Kind**: instance method of [DocumentHistory](#DocumentHistory) - - - -### DocumentHistory.fromJSON(json) ⇒ [DocumentHistory](#DocumentHistory) - -Deserializes `DocumentHistory` from a JSON object. - -**Kind**: static method of [DocumentHistory](#DocumentHistory) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## DocumentMetadata - -Additional attributes related to an IOTA DID Document. - -**Kind**: global class - -- [DocumentMetadata](#DocumentMetadata) - - [.previousMessageId](#DocumentMetadata+previousMessageId) ⇒ string - - [.created()](#DocumentMetadata+created) ⇒ [Timestamp](#Timestamp) \| undefined - - [.updated()](#DocumentMetadata+updated) ⇒ [Timestamp](#Timestamp) \| undefined - - [.clone()](#DocumentMetadata+clone) ⇒ [DocumentMetadata](#DocumentMetadata) - - - -### documentMetadata.previousMessageId ⇒ string - -**Kind**: instance property of [DocumentMetadata](#DocumentMetadata) - - - -### documentMetadata.created() ⇒ [Timestamp](#Timestamp) \| undefined - -Returns a copy of the timestamp of when the DID document was created. - -**Kind**: instance method of [DocumentMetadata](#DocumentMetadata) - - - -### documentMetadata.updated() ⇒ [Timestamp](#Timestamp) \| undefined - -Returns a copy of the timestamp of the last DID document update. - -**Kind**: instance method of [DocumentMetadata](#DocumentMetadata) - - - -### documentMetadata.clone() ⇒ [DocumentMetadata](#DocumentMetadata) - -Deep clones the object. - -**Kind**: instance method of [DocumentMetadata](#DocumentMetadata) - - - -## Duration - -A span of time. - -**Kind**: global class - -- [Duration](#Duration) - - _instance_ - - [.toJSON()](#Duration+toJSON) ⇒ any - - _static_ - - [.seconds(seconds)](#Duration.seconds) ⇒ [Duration](#Duration) - - [.minutes(minutes)](#Duration.minutes) ⇒ [Duration](#Duration) - - [.hours(hours)](#Duration.hours) ⇒ [Duration](#Duration) - - [.days(days)](#Duration.days) ⇒ [Duration](#Duration) - - [.weeks(weeks)](#Duration.weeks) ⇒ [Duration](#Duration) - - [.fromJSON(json)](#Duration.fromJSON) ⇒ [Duration](#Duration) - - - -### duration.toJSON() ⇒ any - -Serializes a `Duration` as a JSON object. - -**Kind**: instance method of [Duration](#Duration) - - - -### Duration.seconds(seconds) ⇒ [Duration](#Duration) - -Create a new `Duration` with the given number of seconds. - -**Kind**: static method of [Duration](#Duration) - -| Param | Type | -| ------- | ------------------- | -| seconds | number | - - - -### Duration.minutes(minutes) ⇒ [Duration](#Duration) - -Create a new `Duration` with the given number of minutes. - -**Kind**: static method of [Duration](#Duration) - -| Param | Type | -| ------- | ------------------- | -| minutes | number | - - - -### Duration.hours(hours) ⇒ [Duration](#Duration) - -Create a new `Duration` with the given number of hours. - -**Kind**: static method of [Duration](#Duration) - -| Param | Type | -| ----- | ------------------- | -| hours | number | - - - -### Duration.days(days) ⇒ [Duration](#Duration) - -Create a new `Duration` with the given number of days. - -**Kind**: static method of [Duration](#Duration) - -| Param | Type | -| ----- | ------------------- | -| days | number | - - - -### Duration.weeks(weeks) ⇒ [Duration](#Duration) - -Create a new `Duration` with the given number of weeks. - -**Kind**: static method of [Duration](#Duration) - -| Param | Type | -| ----- | ------------------- | -| weeks | number | - - - -### Duration.fromJSON(json) ⇒ [Duration](#Duration) - -Deserializes a `Duration` from a JSON object. - -**Kind**: static method of [Duration](#Duration) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## Ed25519 - -**Kind**: global class - -- [Ed25519](#Ed25519) - - [.PRIVATE_KEY_LENGTH()](#Ed25519.PRIVATE_KEY_LENGTH) ⇒ number - - [.PUBLIC_KEY_LENGTH()](#Ed25519.PUBLIC_KEY_LENGTH) ⇒ number - - [.SIGNATURE_LENGTH()](#Ed25519.SIGNATURE_LENGTH) ⇒ number - - [.sign(message, privateKey)](#Ed25519.sign) ⇒ Uint8Array - - [.verify(message, signature, publicKey)](#Ed25519.verify) - - - -### Ed25519.PRIVATE_KEY_LENGTH() ⇒ number - -Length in bytes of an Ed25519 private key. - -**Kind**: static method of [Ed25519](#Ed25519) - - - -### Ed25519.PUBLIC_KEY_LENGTH() ⇒ number - -Length in bytes of an Ed25519 public key. - -**Kind**: static method of [Ed25519](#Ed25519) - - - -### Ed25519.SIGNATURE_LENGTH() ⇒ number - -Length in bytes of an Ed25519 signature. - -**Kind**: static method of [Ed25519](#Ed25519) - - - -### Ed25519.sign(message, privateKey) ⇒ Uint8Array - -Computes an EdDSA signature using an Ed25519 private key. - -NOTE: this differs from [Document.signData](#Document+signData) which uses JCS -to canonicalize JSON messages. - -The private key must be a 32-byte seed in compliance with [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2). -Other implementations often use another format. See [this blog post](https://blog.mozilla.org/warner/2011/11/29/ed25519-keys/) for further explanation. - -**Kind**: static method of [Ed25519](#Ed25519) - -| Param | Type | -| ---------- | ----------------------- | -| message | Uint8Array | -| privateKey | Uint8Array | - - - -### Ed25519.verify(message, signature, publicKey) - -Verifies an EdDSA signature against an Ed25519 public key. - -NOTE: this differs from [Document.verifyData](#Document+verifyData) which uses JCS -to canonicalize JSON messages. - -**Kind**: static method of [Ed25519](#Ed25519) - -| Param | Type | -| --------- | ----------------------- | -| message | Uint8Array | -| signature | Uint8Array | -| publicKey | Uint8Array | - - - -## EncryptedData - -The structure returned after encrypting data - -**Kind**: global class - -- [EncryptedData](#EncryptedData) - - _instance_ - - [.nonce()](#EncryptedData+nonce) ⇒ Uint8Array - - [.associatedData()](#EncryptedData+associatedData) ⇒ Uint8Array - - [.ciphertext()](#EncryptedData+ciphertext) ⇒ Uint8Array - - [.tag()](#EncryptedData+tag) ⇒ Uint8Array - - [.toJSON()](#EncryptedData+toJSON) ⇒ any - - _static_ - - [.fromJSON(json_value)](#EncryptedData.fromJSON) ⇒ [EncryptedData](#EncryptedData) - - - -### encryptedData.nonce() ⇒ Uint8Array - -Returns a copy of the nonce - -**Kind**: instance method of [EncryptedData](#EncryptedData) - - - -### encryptedData.associatedData() ⇒ Uint8Array - -Returns a copy of the associated data - -**Kind**: instance method of [EncryptedData](#EncryptedData) - - - -### encryptedData.ciphertext() ⇒ Uint8Array - -Returns a copy of the ciphertext - -**Kind**: instance method of [EncryptedData](#EncryptedData) - - - -### encryptedData.tag() ⇒ Uint8Array - -Returns a copy of the tag - -**Kind**: instance method of [EncryptedData](#EncryptedData) - - - -### encryptedData.toJSON() ⇒ any - -Serializes `EncryptedData` as a JSON object. - -**Kind**: instance method of [EncryptedData](#EncryptedData) - - - -### EncryptedData.fromJSON(json_value) ⇒ [EncryptedData](#EncryptedData) - -Deserializes `EncryptedData` from a JSON object. - -**Kind**: static method of [EncryptedData](#EncryptedData) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## EncryptionAlgorithm - -Supported content encryption algorithms. - -**Kind**: global class - -- [EncryptionAlgorithm](#EncryptionAlgorithm) - - _instance_ - - [.keyLength()](#EncryptionAlgorithm+keyLength) ⇒ number - - [.toJSON()](#EncryptionAlgorithm+toJSON) ⇒ any - - _static_ - - [.A256GCM()](#EncryptionAlgorithm.A256GCM) ⇒ [EncryptionAlgorithm](#EncryptionAlgorithm) - - [.fromJSON(json_value)](#EncryptionAlgorithm.fromJSON) ⇒ [EncryptionAlgorithm](#EncryptionAlgorithm) - - - -### encryptionAlgorithm.keyLength() ⇒ number - -Returns the length of the cipher's key. - -**Kind**: instance method of [EncryptionAlgorithm](#EncryptionAlgorithm) - - - -### encryptionAlgorithm.toJSON() ⇒ any - -Serializes `EncryptionAlgorithm` as a JSON object. - -**Kind**: instance method of [EncryptionAlgorithm](#EncryptionAlgorithm) - - - -### EncryptionAlgorithm.A256GCM() ⇒ [EncryptionAlgorithm](#EncryptionAlgorithm) - -AES GCM using 256-bit key. - -**Kind**: static method of [EncryptionAlgorithm](#EncryptionAlgorithm) - - - -### EncryptionAlgorithm.fromJSON(json_value) ⇒ [EncryptionAlgorithm](#EncryptionAlgorithm) - -Deserializes `EncryptionAlgorithm` from a JSON object. - -**Kind**: static method of [EncryptionAlgorithm](#EncryptionAlgorithm) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## ExplorerUrl - -**Kind**: global class - -- [ExplorerUrl](#ExplorerUrl) - - _instance_ - - [.messageUrl(message_id)](#ExplorerUrl+messageUrl) ⇒ string - - [.resolverUrl(did)](#ExplorerUrl+resolverUrl) ⇒ string - - [.toString()](#ExplorerUrl+toString) ⇒ string - - _static_ - - [.parse(url)](#ExplorerUrl.parse) ⇒ [ExplorerUrl](#ExplorerUrl) - - [.mainnet()](#ExplorerUrl.mainnet) ⇒ [ExplorerUrl](#ExplorerUrl) - - [.devnet()](#ExplorerUrl.devnet) ⇒ [ExplorerUrl](#ExplorerUrl) - - - -### explorerUrl.messageUrl(message_id) ⇒ string - -Returns the web explorer URL of the given `message_id`. - -E.g. https://explorer.iota.org/mainnet/message/{message_id} - -**Kind**: instance method of [ExplorerUrl](#ExplorerUrl) - -| Param | Type | -| ---------- | ------------------- | -| message_id | string | - - - -### explorerUrl.resolverUrl(did) ⇒ string - -Returns the web identity resolver URL for the given DID. - -E.g. https://explorer.iota.org/mainnet/identity-resolver/{did} - -**Kind**: instance method of [ExplorerUrl](#ExplorerUrl) - -| Param | Type | -| ----- | ----------------------------------------------- | -| did | [DID](#DID) \| string | - - - -### explorerUrl.toString() ⇒ string - -**Kind**: instance method of [ExplorerUrl](#ExplorerUrl) - - - -### ExplorerUrl.parse(url) ⇒ [ExplorerUrl](#ExplorerUrl) - -Constructs a new Tangle explorer URL from a string. - -Use `ExplorerUrl::mainnet` or `ExplorerUrl::devnet` unless using a private Tangle -or local explorer. - -**Kind**: static method of [ExplorerUrl](#ExplorerUrl) - -| Param | Type | -| ----- | ------------------- | -| url | string | - - - -### ExplorerUrl.mainnet() ⇒ [ExplorerUrl](#ExplorerUrl) - -Returns the Tangle explorer URL for the mainnet. - -**Kind**: static method of [ExplorerUrl](#ExplorerUrl) - - - -### ExplorerUrl.devnet() ⇒ [ExplorerUrl](#ExplorerUrl) - -Returns the Tangle explorer URL for the devnet. - -**Kind**: static method of [ExplorerUrl](#ExplorerUrl) - - - -## IntegrationChainHistory - -**Kind**: global class - -- [IntegrationChainHistory](#IntegrationChainHistory) - - _instance_ - - [.chainData()](#IntegrationChainHistory+chainData) ⇒ [Array.<ResolvedDocument>](#ResolvedDocument) - - [.spam()](#IntegrationChainHistory+spam) ⇒ Array.<string> - - [.toJSON()](#IntegrationChainHistory+toJSON) ⇒ any - - _static_ - - [.fromJSON(json)](#IntegrationChainHistory.fromJSON) ⇒ [IntegrationChainHistory](#IntegrationChainHistory) - - - -### integrationChainHistory.chainData() ⇒ [Array.<ResolvedDocument>](#ResolvedDocument) - -Returns an `Array` of the integration chain `Documents`. - -NOTE: this clones the field. - -**Kind**: instance method of [IntegrationChainHistory](#IntegrationChainHistory) - - - -### integrationChainHistory.spam() ⇒ Array.<string> - -Returns an `Array` of `MessageIds` as strings. - -NOTE: this clones the field. - -**Kind**: instance method of [IntegrationChainHistory](#IntegrationChainHistory) - - - -### integrationChainHistory.toJSON() ⇒ any - -Serializes as a JSON object. - -**Kind**: instance method of [IntegrationChainHistory](#IntegrationChainHistory) - - - -### IntegrationChainHistory.fromJSON(json) ⇒ [IntegrationChainHistory](#IntegrationChainHistory) - -Deserializes from a JSON object. - -**Kind**: static method of [IntegrationChainHistory](#IntegrationChainHistory) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## KeyLocation - -The storage location of a verification method key. - -A key is uniquely identified by the fragment and a hash of its public key. -Importantly, the fragment alone is insufficient to represent the storage location. -For example, when rotating a key, there will be two keys in storage for the -same identity with the same fragment. The `key_hash` disambiguates the keys in -situations like these. - -The string representation of that location can be obtained via `canonicalRepr`. - -**Kind**: global class - -- [KeyLocation](#KeyLocation) - - [new KeyLocation(keyType, fragment, publicKey)](#new_KeyLocation_new) - - _instance_ - - [.canonical()](#KeyLocation+canonical) ⇒ string - - [.keyType()](#KeyLocation+keyType) ⇒ number - - [.toJSON()](#KeyLocation+toJSON) ⇒ any - - [.toString()](#KeyLocation+toString) ⇒ string - - _static_ - - [.fromVerificationMethod(method)](#KeyLocation.fromVerificationMethod) ⇒ [KeyLocation](#KeyLocation) - - [.fromJSON(json_value)](#KeyLocation.fromJSON) ⇒ [KeyLocation](#KeyLocation) - - - -### new KeyLocation(keyType, fragment, publicKey) - -Create a location from a `KeyType`, the fragment of a verification method -and the bytes of a public key. - -| Param | Type | -| --------- | ----------------------- | -| keyType | number | -| fragment | string | -| publicKey | Uint8Array | - - - -### keyLocation.canonical() ⇒ string - -Returns the canonical string representation of the location. - -This should be used as the representation for storage keys. - -**Kind**: instance method of [KeyLocation](#KeyLocation) - - - -### keyLocation.keyType() ⇒ number - -Returns a copy of the key type of the key location. - -**Kind**: instance method of [KeyLocation](#KeyLocation) - - - -### keyLocation.toJSON() ⇒ any - -Serializes `KeyLocation` as a JSON object. - -**Kind**: instance method of [KeyLocation](#KeyLocation) - - - -### keyLocation.toString() ⇒ string - -**Kind**: instance method of [KeyLocation](#KeyLocation) - - - -### KeyLocation.fromVerificationMethod(method) ⇒ [KeyLocation](#KeyLocation) - -Obtain the location of a verification method's key in storage. - -**Kind**: static method of [KeyLocation](#KeyLocation) - -| Param | Type | -| ------ | ------------------------------------------------------ | -| method | [VerificationMethod](#VerificationMethod) | - - - -### KeyLocation.fromJSON(json_value) ⇒ [KeyLocation](#KeyLocation) - -Deserializes a JSON object into a `KeyLocation`. - -**Kind**: static method of [KeyLocation](#KeyLocation) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## KeyPair - -**Kind**: global class - -- [KeyPair](#KeyPair) - - [new KeyPair(type\_)](#new_KeyPair_new) - - _instance_ - - [.type()](#KeyPair+type) ⇒ number - - [.public()](#KeyPair+public) ⇒ Uint8Array - - [.private()](#KeyPair+private) ⇒ Uint8Array - - [.toJSON()](#KeyPair+toJSON) ⇒ any - - [.clone()](#KeyPair+clone) ⇒ [KeyPair](#KeyPair) - - _static_ - - [.fromKeys(type\_, public_key, private_key)](#KeyPair.fromKeys) ⇒ [KeyPair](#KeyPair) - - [.tryFromPrivateKeyBytes(keyType, privateKeyBytes)](#KeyPair.tryFromPrivateKeyBytes) ⇒ [KeyPair](#KeyPair) - - [.fromJSON(json)](#KeyPair.fromJSON) ⇒ [KeyPair](#KeyPair) - - - -### new KeyPair(type\_) - -Generates a new `KeyPair` object. - -| Param | Type | -| ------ | ------------------- | -| type\_ | number | - - - -### keyPair.type() ⇒ number - -Returns the `KeyType` of the `KeyPair` object. - -**Kind**: instance method of [KeyPair](#KeyPair) - - - -### keyPair.public() ⇒ Uint8Array - -Returns a copy of the public key as a `Uint8Array`. - -**Kind**: instance method of [KeyPair](#KeyPair) - - - -### keyPair.private() ⇒ Uint8Array - -Returns a copy of the private key as a `Uint8Array`. - -**Kind**: instance method of [KeyPair](#KeyPair) - - - -### keyPair.toJSON() ⇒ any - -Serializes a `KeyPair` object as a JSON object. - -**Kind**: instance method of [KeyPair](#KeyPair) - - - -### keyPair.clone() ⇒ [KeyPair](#KeyPair) - -Deep clones the object. - -**Kind**: instance method of [KeyPair](#KeyPair) - - - -### KeyPair.fromKeys(type\_, public_key, private_key) ⇒ [KeyPair](#KeyPair) - -Parses a `KeyPair` object from the public/private keys. - -**Kind**: static method of [KeyPair](#KeyPair) - -| Param | Type | -| ----------- | ----------------------- | -| type\_ | number | -| public_key | Uint8Array | -| private_key | Uint8Array | - - - -### KeyPair.tryFromPrivateKeyBytes(keyType, privateKeyBytes) ⇒ [KeyPair](#KeyPair) - -Reconstructs a `KeyPair` from the bytes of a private key. - -The private key for `Ed25519` must be a 32-byte seed in compliance -with [RFC 8032](https://datatracker.ietf.org/doc/html/rfc8032#section-3.2). -Other implementations often use another format. See [this blog post](https://blog.mozilla.org/warner/2011/11/29/ed25519-keys/) for further explanation. - -**Kind**: static method of [KeyPair](#KeyPair) - -| Param | Type | -| --------------- | ----------------------- | -| keyType | number | -| privateKeyBytes | Uint8Array | - - - -### KeyPair.fromJSON(json) ⇒ [KeyPair](#KeyPair) - -Deserializes a `KeyPair` object from a JSON object. - -**Kind**: static method of [KeyPair](#KeyPair) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## MethodContent - -**Kind**: global class - -- [MethodContent](#MethodContent) - - _instance_ - - [.toJSON()](#MethodContent+toJSON) ⇒ any - - _static_ - - [.GenerateEd25519()](#MethodContent.GenerateEd25519) ⇒ [MethodContent](#MethodContent) - - [.PrivateEd25519(privateKey)](#MethodContent.PrivateEd25519) ⇒ [MethodContent](#MethodContent) - - [.PublicEd25519(publicKey)](#MethodContent.PublicEd25519) ⇒ [MethodContent](#MethodContent) - - [.GenerateX25519()](#MethodContent.GenerateX25519) ⇒ [MethodContent](#MethodContent) - - [.PrivateX25519(privateKey)](#MethodContent.PrivateX25519) ⇒ [MethodContent](#MethodContent) - - [.PublicX25519(publicKey)](#MethodContent.PublicX25519) ⇒ [MethodContent](#MethodContent) - - [.fromJSON(json_value)](#MethodContent.fromJSON) ⇒ [MethodContent](#MethodContent) - - - -### methodContent.toJSON() ⇒ any - -Serializes `MethodContent` as a JSON object. - -**Kind**: instance method of [MethodContent](#MethodContent) - - - -### MethodContent.GenerateEd25519() ⇒ [MethodContent](#MethodContent) - -Generate and store a new Ed25519 keypair for a new `Ed25519VerificationKey2018` method. - -**Kind**: static method of [MethodContent](#MethodContent) - - - -### MethodContent.PrivateEd25519(privateKey) ⇒ [MethodContent](#MethodContent) - -Store an existing Ed25519 private key and derive a public key from it for a new -`Ed25519VerificationKey2018` method. - -**Kind**: static method of [MethodContent](#MethodContent) - -| Param | Type | -| ---------- | ----------------------- | -| privateKey | Uint8Array | - - - -### MethodContent.PublicEd25519(publicKey) ⇒ [MethodContent](#MethodContent) - -Insert an existing Ed25519 public key into a new `Ed25519VerificationKey2018` method, -without generating or storing a private key. - -NOTE: the method will be unable to be used to sign anything without a private key. - -**Kind**: static method of [MethodContent](#MethodContent) - -| Param | Type | -| --------- | ----------------------- | -| publicKey | Uint8Array | - - - -### MethodContent.GenerateX25519() ⇒ [MethodContent](#MethodContent) - -Generate and store a new X25519 keypair for a new `X25519KeyAgreementKey2019` method. - -**Kind**: static method of [MethodContent](#MethodContent) - - - -### MethodContent.PrivateX25519(privateKey) ⇒ [MethodContent](#MethodContent) - -Store an existing X25519 private key and derive a public key from it for a new -`X25519KeyAgreementKey2019` method. - -**Kind**: static method of [MethodContent](#MethodContent) - -| Param | Type | -| ---------- | ----------------------- | -| privateKey | Uint8Array | - - - -### MethodContent.PublicX25519(publicKey) ⇒ [MethodContent](#MethodContent) - -Insert an existing X25519 public key into a new `X25519KeyAgreementKey2019` method, -without generating or storing a private key. - -NOTE: the method will be unable to be used for key exchange without a private key. - -**Kind**: static method of [MethodContent](#MethodContent) - -| Param | Type | -| --------- | ----------------------- | -| publicKey | Uint8Array | - - - -### MethodContent.fromJSON(json_value) ⇒ [MethodContent](#MethodContent) - -Deserializes `MethodContent` from a JSON object. - -**Kind**: static method of [MethodContent](#MethodContent) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## MethodData - -Supported verification method data formats. - -**Kind**: global class - -- [MethodData](#MethodData) - - _instance_ - - [.tryDecode()](#MethodData+tryDecode) ⇒ Uint8Array - - [.toJSON()](#MethodData+toJSON) ⇒ any - - [.clone()](#MethodData+clone) ⇒ [MethodData](#MethodData) - - _static_ - - [.newBase58(data)](#MethodData.newBase58) ⇒ [MethodData](#MethodData) - - [.newMultibase(data)](#MethodData.newMultibase) ⇒ [MethodData](#MethodData) - - [.fromJSON(json)](#MethodData.fromJSON) ⇒ [MethodData](#MethodData) - - - -### methodData.tryDecode() ⇒ Uint8Array - -Returns a `Uint8Array` containing the decoded bytes of the `MethodData`. - -This is generally a public key identified by a `MethodData` value. - -### Errors - -Decoding can fail if `MethodData` has invalid content or cannot be -represented as a vector of bytes. - -**Kind**: instance method of [MethodData](#MethodData) - - - -### methodData.toJSON() ⇒ any - -Serializes a `MethodData` object as a JSON object. - -**Kind**: instance method of [MethodData](#MethodData) - - - -### methodData.clone() ⇒ [MethodData](#MethodData) - -Deep clones the object. - -**Kind**: instance method of [MethodData](#MethodData) - - - -### MethodData.newBase58(data) ⇒ [MethodData](#MethodData) - -Creates a new `MethodData` variant with Base58-BTC encoded content. - -**Kind**: static method of [MethodData](#MethodData) - -| Param | Type | -| ----- | ----------------------- | -| data | Uint8Array | - - - -### MethodData.newMultibase(data) ⇒ [MethodData](#MethodData) - -Creates a new `MethodData` variant with Multibase-encoded content. - -**Kind**: static method of [MethodData](#MethodData) - -| Param | Type | -| ----- | ----------------------- | -| data | Uint8Array | - - - -### MethodData.fromJSON(json) ⇒ [MethodData](#MethodData) - -Deserializes a `MethodData` object from a JSON object. - -**Kind**: static method of [MethodData](#MethodData) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## MethodScope - -Supported verification method types. - -**Kind**: global class - -- [MethodScope](#MethodScope) - - _instance_ - - [.toString()](#MethodScope+toString) ⇒ string - - [.toJSON()](#MethodScope+toJSON) ⇒ any - - [.clone()](#MethodScope+clone) ⇒ [MethodScope](#MethodScope) - - _static_ - - [.VerificationMethod()](#MethodScope.VerificationMethod) ⇒ [MethodScope](#MethodScope) - - [.Authentication()](#MethodScope.Authentication) ⇒ [MethodScope](#MethodScope) - - [.AssertionMethod()](#MethodScope.AssertionMethod) ⇒ [MethodScope](#MethodScope) - - [.KeyAgreement()](#MethodScope.KeyAgreement) ⇒ [MethodScope](#MethodScope) - - [.CapabilityDelegation()](#MethodScope.CapabilityDelegation) ⇒ [MethodScope](#MethodScope) - - [.CapabilityInvocation()](#MethodScope.CapabilityInvocation) ⇒ [MethodScope](#MethodScope) - - [.fromJSON(json)](#MethodScope.fromJSON) ⇒ [MethodScope](#MethodScope) - - - -### methodScope.toString() ⇒ string - -Returns the `MethodScope` as a string. - -**Kind**: instance method of [MethodScope](#MethodScope) - - - -### methodScope.toJSON() ⇒ any - -Serializes a `MethodScope` object as a JSON object. - -**Kind**: instance method of [MethodScope](#MethodScope) - - - -### methodScope.clone() ⇒ [MethodScope](#MethodScope) - -Deep clones the object. - -**Kind**: instance method of [MethodScope](#MethodScope) - - - -### MethodScope.VerificationMethod() ⇒ [MethodScope](#MethodScope) - -**Kind**: static method of [MethodScope](#MethodScope) - - - -### MethodScope.Authentication() ⇒ [MethodScope](#MethodScope) - -**Kind**: static method of [MethodScope](#MethodScope) - - - -### MethodScope.AssertionMethod() ⇒ [MethodScope](#MethodScope) - -**Kind**: static method of [MethodScope](#MethodScope) - - - -### MethodScope.KeyAgreement() ⇒ [MethodScope](#MethodScope) - -**Kind**: static method of [MethodScope](#MethodScope) - - - -### MethodScope.CapabilityDelegation() ⇒ [MethodScope](#MethodScope) - -**Kind**: static method of [MethodScope](#MethodScope) - - - -### MethodScope.CapabilityInvocation() ⇒ [MethodScope](#MethodScope) - -**Kind**: static method of [MethodScope](#MethodScope) - - - -### MethodScope.fromJSON(json) ⇒ [MethodScope](#MethodScope) - -Deserializes a `MethodScope` object from a JSON object. - -**Kind**: static method of [MethodScope](#MethodScope) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## MethodType - -Supported verification method types. - -**Kind**: global class - -- [MethodType](#MethodType) - - _instance_ - - [.toJSON()](#MethodType+toJSON) ⇒ any - - [.toString()](#MethodType+toString) ⇒ string - - [.clone()](#MethodType+clone) ⇒ [MethodType](#MethodType) - - _static_ - - [.Ed25519VerificationKey2018()](#MethodType.Ed25519VerificationKey2018) ⇒ [MethodType](#MethodType) - - [.X25519KeyAgreementKey2019()](#MethodType.X25519KeyAgreementKey2019) ⇒ [MethodType](#MethodType) - - [.fromJSON(json)](#MethodType.fromJSON) ⇒ [MethodType](#MethodType) - - - -### methodType.toJSON() ⇒ any - -Serializes a `MethodType` object as a JSON object. - -**Kind**: instance method of [MethodType](#MethodType) - - - -### methodType.toString() ⇒ string - -Returns the `MethodType` as a string. - -**Kind**: instance method of [MethodType](#MethodType) - - - -### methodType.clone() ⇒ [MethodType](#MethodType) - -Deep clones the object. - -**Kind**: instance method of [MethodType](#MethodType) - - - -### MethodType.Ed25519VerificationKey2018() ⇒ [MethodType](#MethodType) - -**Kind**: static method of [MethodType](#MethodType) - - - -### MethodType.X25519KeyAgreementKey2019() ⇒ [MethodType](#MethodType) - -**Kind**: static method of [MethodType](#MethodType) - - - -### MethodType.fromJSON(json) ⇒ [MethodType](#MethodType) - -Deserializes a `MethodType` object from a JSON object. - -**Kind**: static method of [MethodType](#MethodType) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## Network - -**Kind**: global class - -- [Network](#Network) - - _instance_ - - [.name()](#Network+name) ⇒ string - - [.defaultNodeURL()](#Network+defaultNodeURL) ⇒ string \| undefined - - [.toString()](#Network+toString) ⇒ string - - [.toJSON()](#Network+toJSON) ⇒ any - - [.clone()](#Network+clone) ⇒ [Network](#Network) - - _static_ - - [.tryFromName(name)](#Network.tryFromName) ⇒ [Network](#Network) - - [.mainnet()](#Network.mainnet) ⇒ [Network](#Network) - - [.devnet()](#Network.devnet) ⇒ [Network](#Network) - - [.fromJSON(json)](#Network.fromJSON) ⇒ [Network](#Network) - - - -### network.name() ⇒ string - -Returns a copy of the network name. - -**Kind**: instance method of [Network](#Network) - - - -### network.defaultNodeURL() ⇒ string \| undefined - -Returns a copy of the node URL of the Tangle network. - -**Kind**: instance method of [Network](#Network) - - - -### network.toString() ⇒ string - -**Kind**: instance method of [Network](#Network) - - - -### network.toJSON() ⇒ any - -Serializes a `Network` as a JSON object. - -**Kind**: instance method of [Network](#Network) - - - -### network.clone() ⇒ [Network](#Network) - -Deep clones the object. - -**Kind**: instance method of [Network](#Network) - - - -### Network.tryFromName(name) ⇒ [Network](#Network) - -Parses the provided string to a `Network`. - -Errors if the name is invalid. - -**Kind**: static method of [Network](#Network) - -| Param | Type | -| ----- | ------------------- | -| name | string | - - - -### Network.mainnet() ⇒ [Network](#Network) - -**Kind**: static method of [Network](#Network) - - - -### Network.devnet() ⇒ [Network](#Network) - -**Kind**: static method of [Network](#Network) - - - -### Network.fromJSON(json) ⇒ [Network](#Network) - -Deserializes a `Network` from a JSON object. - -**Kind**: static method of [Network](#Network) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## Presentation - -**Kind**: global class - -- [Presentation](#Presentation) - - [new Presentation(values)](#new_Presentation_new) - - _instance_ - - [.context()](#Presentation+context) ⇒ Array.<(string\|Record.<string, any>)> - - [.id()](#Presentation+id) ⇒ string \| undefined - - [.type()](#Presentation+type) ⇒ Array.<string> - - [.verifiableCredential()](#Presentation+verifiableCredential) ⇒ [Array.<Credential>](#Credential) - - [.holder()](#Presentation+holder) ⇒ string \| undefined - - [.refreshService()](#Presentation+refreshService) ⇒ Array.<RefreshService> - - [.termsOfUse()](#Presentation+termsOfUse) ⇒ Array.<Policy> - - [.proof()](#Presentation+proof) ⇒ [Proof](#Proof) \| undefined - - [.properties()](#Presentation+properties) ⇒ Map.<string, any> - - [.toJSON()](#Presentation+toJSON) ⇒ any - - [.clone()](#Presentation+clone) ⇒ [Presentation](#Presentation) - - _static_ - - [.BaseContext()](#Presentation.BaseContext) ⇒ string - - [.BaseType()](#Presentation.BaseType) ⇒ string - - [.fromJSON(json)](#Presentation.fromJSON) ⇒ [Presentation](#Presentation) - - - -### new Presentation(values) - -Constructs a new `Presentation`. - -| Param | Type | -| ------ | -------------------------- | -| values | IPresentation | - - - -### presentation.context() ⇒ Array.<(string\|Record.<string, any>)> - -Returns a copy of the JSON-LD context(s) applicable to the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.id() ⇒ string \| undefined - -Returns a copy of the unique `URI` identifying the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.type() ⇒ Array.<string> - -Returns a copy of the URIs defining the type of the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.verifiableCredential() ⇒ [Array.<Credential>](#Credential) - -Returns a copy of the [Credential](#Credential)(s) expressing the claims of the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.holder() ⇒ string \| undefined - -Returns a copy of the URI of the entity that generated the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.refreshService() ⇒ Array.<RefreshService> - -Returns a copy of the service(s) used to refresh an expired [Credential](#Credential) in the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.termsOfUse() ⇒ Array.<Policy> - -Returns a copy of the terms-of-use specified by the `Presentation` holder - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.proof() ⇒ [Proof](#Proof) \| undefined - -Returns a copy of the proof used to verify the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.properties() ⇒ Map.<string, any> - -Returns a copy of the miscellaneous properties on the `Presentation`. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.toJSON() ⇒ any - -Serializes a `Presentation` as a JSON object. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### presentation.clone() ⇒ [Presentation](#Presentation) - -Deep clones the object. - -**Kind**: instance method of [Presentation](#Presentation) - - - -### Presentation.BaseContext() ⇒ string - -Returns the base JSON-LD context. - -**Kind**: static method of [Presentation](#Presentation) - - - -### Presentation.BaseType() ⇒ string - -Returns the base type. - -**Kind**: static method of [Presentation](#Presentation) - - - -### Presentation.fromJSON(json) ⇒ [Presentation](#Presentation) - -Deserializes a `Presentation` from a JSON object. - -**Kind**: static method of [Presentation](#Presentation) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## PresentationValidationOptions - -Options to declare validation criteria when validating presentation. - -**Kind**: global class - -- [PresentationValidationOptions](#PresentationValidationOptions) - - [new PresentationValidationOptions(options)](#new_PresentationValidationOptions_new) - - _instance_ - - [.toJSON()](#PresentationValidationOptions+toJSON) ⇒ any - - [.clone()](#PresentationValidationOptions+clone) ⇒ [PresentationValidationOptions](#PresentationValidationOptions) - - _static_ - - [.default()](#PresentationValidationOptions.default) ⇒ [PresentationValidationOptions](#PresentationValidationOptions) - - [.fromJSON(json)](#PresentationValidationOptions.fromJSON) ⇒ [PresentationValidationOptions](#PresentationValidationOptions) - - - -### new PresentationValidationOptions(options) - -Creates a new `PresentationValidationOptions` from the given fields. - -Throws an error if any of the options are invalid. - -| Param | Type | -| ------- | ------------------------------------------- | -| options | IPresentationValidationOptions | - - - -### presentationValidationOptions.toJSON() ⇒ any - -Serializes a `PresentationValidationOptions` as a JSON object. - -**Kind**: instance method of [PresentationValidationOptions](#PresentationValidationOptions) - - - -### presentationValidationOptions.clone() ⇒ [PresentationValidationOptions](#PresentationValidationOptions) - -Deep clones the object. - -**Kind**: instance method of [PresentationValidationOptions](#PresentationValidationOptions) - - - -### PresentationValidationOptions.default() ⇒ [PresentationValidationOptions](#PresentationValidationOptions) - -Creates a new `PresentationValidationOptions` with defaults. - -**Kind**: static method of [PresentationValidationOptions](#PresentationValidationOptions) - - - -### PresentationValidationOptions.fromJSON(json) ⇒ [PresentationValidationOptions](#PresentationValidationOptions) - -Deserializes a `PresentationValidationOptions` from a JSON object. - -**Kind**: static method of [PresentationValidationOptions](#PresentationValidationOptions) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## PresentationValidator - -**Kind**: global class - -- [PresentationValidator](#PresentationValidator) - - [.validate(presentation, holder, issuers, options, fail_fast)](#PresentationValidator.validate) - - [.verifyPresentationSignature(presentation, holder, options)](#PresentationValidator.verifyPresentationSignature) - - [.checkStructure(presentation)](#PresentationValidator.checkStructure) - - - -### PresentationValidator.validate(presentation, holder, issuers, options, fail_fast) - -Validate a `Presentation`. - -The following properties are validated according to `options`: - -- the semantic structure of the presentation, -- the holder's signature, -- the relationship between the holder and the credential subjects, -- the signatures and some properties of the constituent credentials (see - `CredentialValidator::validate`). - -### Warning - -The lack of an error returned from this method is in of itself not enough to conclude that the presentation can be -trusted. This section contains more information on additional checks that should be carried out before and after -calling this method. - -#### The state of the supplied DID Documents - -The caller must ensure that the DID Documents in `holder` and `issuers` are up-to-date. The convenience methods -`Resolver::resolve_presentation_holder` and `Resolver::resolve_presentation_issuers` -can help extract the latest available states of these DID Documents. - -#### Properties that are not validated - -There are many properties defined in [The Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) that are **not** validated, such as: -`credentialStatus`, `type`, `credentialSchema`, `refreshService`, **and more**. -These should be manually checked after validation, according to your requirements. - -### Errors - -An error is returned whenever a validated condition is not satisfied. - -**Kind**: static method of [PresentationValidator](#PresentationValidator) - -| Param | Type | -| ------------ | -------------------------------------------------------------------------------------------------------------------- | -| presentation | [Presentation](#Presentation) | -| holder | [Document](#Document) \| [ResolvedDocument](#ResolvedDocument) | -| issuers | [Array.<Document>](#Document) \| [Array.<ResolvedDocument>](#ResolvedDocument) | -| options | [PresentationValidationOptions](#PresentationValidationOptions) | -| fail_fast | number | - - - -### PresentationValidator.verifyPresentationSignature(presentation, holder, options) - -Verify the presentation's signature using the resolved document of the holder. - -### Warning - -The caller must ensure that the DID Document of the holder is up-to-date. - -### Errors - -Fails if the `holder` does not match the `presentation`'s holder property. -Fails if signature verification against the holder document fails. - -**Kind**: static method of [PresentationValidator](#PresentationValidator) - -| Param | Type | -| ------------ | ---------------------------------------------------------------------------------------- | -| presentation | [Presentation](#Presentation) | -| holder | [Document](#Document) \| [ResolvedDocument](#ResolvedDocument) | -| options | [VerifierOptions](#VerifierOptions) | - - - -### PresentationValidator.checkStructure(presentation) - -Validates the semantic structure of the `Presentation`. - -**Kind**: static method of [PresentationValidator](#PresentationValidator) - -| Param | Type | -| ------------ | ------------------------------------------ | -| presentation | [Presentation](#Presentation) | - - - -## Proof - -A digital signature. - -For field definitions see: https://w3c-ccg.github.io/security-vocab/ - -**Kind**: global class - -- [Proof](#Proof) - - _instance_ - - [.type()](#Proof+type) ⇒ string - - [.value()](#Proof+value) ⇒ string - - [.verificationMethod()](#Proof+verificationMethod) ⇒ string - - [.created()](#Proof+created) ⇒ [Timestamp](#Timestamp) \| undefined - - [.expires()](#Proof+expires) ⇒ [Timestamp](#Timestamp) \| undefined - - [.challenge()](#Proof+challenge) ⇒ string \| undefined - - [.domain()](#Proof+domain) ⇒ string \| undefined - - [.purpose()](#Proof+purpose) ⇒ [ProofPurpose](#ProofPurpose) \| undefined - - [.toJSON()](#Proof+toJSON) ⇒ any - - [.clone()](#Proof+clone) ⇒ [Proof](#Proof) - - _static_ - - [.fromJSON(json)](#Proof.fromJSON) ⇒ [Proof](#Proof) - - - -### proof.type() ⇒ string - -Returns a copy of the proof type. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.value() ⇒ string - -Returns a copy of the proof value string. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.verificationMethod() ⇒ string - -Returns a copy of the identifier of the DID method used to create this proof. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.created() ⇒ [Timestamp](#Timestamp) \| undefined - -When the proof was generated. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.expires() ⇒ [Timestamp](#Timestamp) \| undefined - -When the proof expires. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.challenge() ⇒ string \| undefined - -Challenge from a proof requester to mitigate replay attacks. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.domain() ⇒ string \| undefined - -Domain for which a proof is valid to mitigate replay attacks. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.purpose() ⇒ [ProofPurpose](#ProofPurpose) \| undefined - -Purpose for which the proof was generated. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.toJSON() ⇒ any - -Serializes a `Proof` to a JSON object. - -**Kind**: instance method of [Proof](#Proof) - - - -### proof.clone() ⇒ [Proof](#Proof) - -Deep clones the object. - -**Kind**: instance method of [Proof](#Proof) - - - -### Proof.fromJSON(json) ⇒ [Proof](#Proof) - -Deserializes a `Proof` from a JSON object. - -**Kind**: static method of [Proof](#Proof) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## ProofOptions - -Holds additional options for creating signatures. -See `IProofOptions`. - -**Kind**: global class - -- [ProofOptions](#ProofOptions) - - [new ProofOptions(options)](#new_ProofOptions_new) - - _instance_ - - [.clone()](#ProofOptions+clone) ⇒ [ProofOptions](#ProofOptions) - - _static_ - - [.default()](#ProofOptions.default) ⇒ [ProofOptions](#ProofOptions) - - - -### new ProofOptions(options) - -Creates a new `ProofOptions` from the given fields. - -Throws an error if any of the options are invalid. - -| Param | Type | -| ------- | -------------------------- | -| options | IProofOptions | - - - -### proofOptions.clone() ⇒ [ProofOptions](#ProofOptions) - -Deep clones the object. - -**Kind**: instance method of [ProofOptions](#ProofOptions) - - - -### ProofOptions.default() ⇒ [ProofOptions](#ProofOptions) - -Creates a new `ProofOptions` with default options. - -**Kind**: static method of [ProofOptions](#ProofOptions) - - - -## ProofPurpose - -Associates a purpose with a [Proof](#Proof). - -See https://w3c-ccg.github.io/security-vocab/#proofPurpose - -**Kind**: global class - -- [ProofPurpose](#ProofPurpose) - - _instance_ - - [.toJSON()](#ProofPurpose+toJSON) ⇒ any - - [.clone()](#ProofPurpose+clone) ⇒ [ProofPurpose](#ProofPurpose) - - _static_ - - [.assertionMethod()](#ProofPurpose.assertionMethod) ⇒ [ProofPurpose](#ProofPurpose) - - [.authentication()](#ProofPurpose.authentication) ⇒ [ProofPurpose](#ProofPurpose) - - [.fromJSON(json)](#ProofPurpose.fromJSON) ⇒ [ProofPurpose](#ProofPurpose) - - - -### proofPurpose.toJSON() ⇒ any - -Serializes a `ProofPurpose` to a JSON object. - -**Kind**: instance method of [ProofPurpose](#ProofPurpose) - - - -### proofPurpose.clone() ⇒ [ProofPurpose](#ProofPurpose) - -Deep clones the object. - -**Kind**: instance method of [ProofPurpose](#ProofPurpose) - - - -### ProofPurpose.assertionMethod() ⇒ [ProofPurpose](#ProofPurpose) - -Purpose is to assert a claim. -See https://www.w3.org/TR/did-core/#assertion - -**Kind**: static method of [ProofPurpose](#ProofPurpose) - - - -### ProofPurpose.authentication() ⇒ [ProofPurpose](#ProofPurpose) - -Purpose is to authenticate the signer. -See https://www.w3.org/TR/did-core/#authentication - -**Kind**: static method of [ProofPurpose](#ProofPurpose) - - - -### ProofPurpose.fromJSON(json) ⇒ [ProofPurpose](#ProofPurpose) - -Deserializes a `ProofPurpose` from a JSON object. - -**Kind**: static method of [ProofPurpose](#ProofPurpose) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## Receipt - -**Kind**: global class - -- [Receipt](#Receipt) - - _instance_ - - [.network()](#Receipt+network) ⇒ [Network](#Network) - - [.messageId()](#Receipt+messageId) ⇒ string - - [.networkId()](#Receipt+networkId) ⇒ string - - [.nonce()](#Receipt+nonce) ⇒ string - - [.toJSON()](#Receipt+toJSON) ⇒ any - - [.clone()](#Receipt+clone) ⇒ [Receipt](#Receipt) - - _static_ - - [.fromJSON(json)](#Receipt.fromJSON) ⇒ [Receipt](#Receipt) - - - -### receipt.network() ⇒ [Network](#Network) - -Returns a copy of the associated IOTA Tangle `Network`. - -**Kind**: instance method of [Receipt](#Receipt) - - - -### receipt.messageId() ⇒ string - -Returns a copy of the message `id`. - -**Kind**: instance method of [Receipt](#Receipt) - - - -### receipt.networkId() ⇒ string - -Returns a copy of the message `network_id`. - -**Kind**: instance method of [Receipt](#Receipt) - - - -### receipt.nonce() ⇒ string - -Returns a copy of the message `nonce`. - -**Kind**: instance method of [Receipt](#Receipt) - - - -### receipt.toJSON() ⇒ any - -Serializes a `Receipt` as a JSON object. - -**Kind**: instance method of [Receipt](#Receipt) - - - -### receipt.clone() ⇒ [Receipt](#Receipt) - -Deep clones the object. - -**Kind**: instance method of [Receipt](#Receipt) - - - -### Receipt.fromJSON(json) ⇒ [Receipt](#Receipt) - -Deserializes a `Receipt` from a JSON object. - -**Kind**: static method of [Receipt](#Receipt) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## ResolvedDocument - -An IOTA DID document resolved from the Tangle. Represents an integration chain message possibly -merged with one or more `DiffMessages`. - -**Kind**: global class - -- [ResolvedDocument](#ResolvedDocument) - - _instance_ - - ~~[.mergeDiffMessage(diff_message)](#ResolvedDocument+mergeDiffMessage)~~ - - [.document()](#ResolvedDocument+document) ⇒ [Document](#Document) - - [.intoDocument()](#ResolvedDocument+intoDocument) ⇒ [Document](#Document) - - ~~[.diffMessageId()](#ResolvedDocument+diffMessageId) ⇒ string~~ - - ~~[.setDiffMessageId(value)](#ResolvedDocument+setDiffMessageId)~~ - - [.integrationMessageId()](#ResolvedDocument+integrationMessageId) ⇒ string - - [.setIntegrationMessageId(value)](#ResolvedDocument+setIntegrationMessageId) - - [.toJSON()](#ResolvedDocument+toJSON) ⇒ any - - [.clone()](#ResolvedDocument+clone) ⇒ [ResolvedDocument](#ResolvedDocument) - - _static_ - - [.fromJSON(json)](#ResolvedDocument.fromJSON) ⇒ [ResolvedDocument](#ResolvedDocument) - - - -### ~~resolvedDocument.mergeDiffMessage(diff_message)~~ - -**_Deprecated_** - -Attempts to merge changes from a `DiffMessage` into this document and -updates the `ResolvedDocument::diffMessageId`. - -If merging fails the document remains unmodified, otherwise this represents -the merged document state. - -See `Document::mergeDiff`. - -# Errors - -Fails if the merge operation or signature verification on the diff fails. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - -| Param | Type | -| ------------ | ---------------------------------------- | -| diff_message | [DiffMessage](#DiffMessage) | - - - -### resolvedDocument.document() ⇒ [Document](#Document) - -Returns a copy of the inner DID document. - -NOTE: If the `ResolvedDocument` is no longer needed after calling this method -then consider using `intoDocument()` for efficiency. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - - - -### resolvedDocument.intoDocument() ⇒ [Document](#Document) - -Consumes this object and returns the inner DID document. - -NOTE: trying to use the `ResolvedDocument` after calling this will throw an error. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - - - -### ~~resolvedDocument.diffMessageId() ⇒ string~~ - -**_Deprecated_** - -Returns a copy of the diff chain message id. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - - - -### ~~resolvedDocument.setDiffMessageId(value)~~ - -**_Deprecated_** - -Sets the diff chain message id. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - -| Param | Type | -| ----- | ------------------- | -| value | string | - - - -### resolvedDocument.integrationMessageId() ⇒ string - -Returns a copy of the integration chain message id. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - - - -### resolvedDocument.setIntegrationMessageId(value) - -Sets the integration chain message id. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - -| Param | Type | -| ----- | ------------------- | -| value | string | - - - -### resolvedDocument.toJSON() ⇒ any - -Serializes a `Document` object as a JSON object. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - - - -### resolvedDocument.clone() ⇒ [ResolvedDocument](#ResolvedDocument) - -Deep clones the object. - -**Kind**: instance method of [ResolvedDocument](#ResolvedDocument) - - - -### ResolvedDocument.fromJSON(json) ⇒ [ResolvedDocument](#ResolvedDocument) - -Deserializes a `Document` object from a JSON object. - -**Kind**: static method of [ResolvedDocument](#ResolvedDocument) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## Resolver - -**Kind**: global class - -- [Resolver](#Resolver) - - [new Resolver()](#new_Resolver_new) - - _instance_ - - [.getClient(network_name)](#Resolver+getClient) ⇒ [Client](#Client) \| undefined - - [.resolve(did)](#Resolver+resolve) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - - [.resolveHistory(did)](#Resolver+resolveHistory) ⇒ [Promise.<DocumentHistory>](#DocumentHistory) - - ~~[.resolveDiffHistory(document)](#Resolver+resolveDiffHistory) ⇒ [Promise.<DiffChainHistory>](#DiffChainHistory)~~ - - [.resolveCredentialIssuer(credential)](#Resolver+resolveCredentialIssuer) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - - [.resolvePresentationIssuers(presentation)](#Resolver+resolvePresentationIssuers) ⇒ Promise.<Array.<ResolvedDocument>> - - [.resolvePresentationHolder(presentation)](#Resolver+resolvePresentationHolder) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - - [.verifyPresentation(presentation, options, fail_fast, holder, issuers)](#Resolver+verifyPresentation) ⇒ Promise.<void> - - _static_ - - [.builder()](#Resolver.builder) ⇒ [ResolverBuilder](#ResolverBuilder) - - - -### new Resolver() - -Constructs a new `Resolver` with a default `Client` for -the `Mainnet`. - - - -### resolver.getClient(network_name) ⇒ [Client](#Client) \| undefined - -Returns the `Client` corresponding to the given network name if one exists. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| ------------ | ------------------- | -| network_name | string | - - - -### resolver.resolve(did) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - -Fetches the `Document` of the given `DID`. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| ----- | ----------------------------------------------- | -| did | [DID](#DID) \| string | - - - -### resolver.resolveHistory(did) ⇒ [Promise.<DocumentHistory>](#DocumentHistory) - -Fetches the `DocumentHistory` of the given `DID`. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| ----- | ----------------------------------------------- | -| did | [DID](#DID) \| string | - - - -### ~~resolver.resolveDiffHistory(document) ⇒ [Promise.<DiffChainHistory>](#DiffChainHistory)~~ - -**_Deprecated_** - -Returns the `DiffChainHistory` of a diff chain starting from a `Document` on the -integration chain. - -NOTE: the document must have been published to the Tangle and have a valid message id. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| -------- | -------------------------------------------------- | -| document | [ResolvedDocument](#ResolvedDocument) | - - - -### resolver.resolveCredentialIssuer(credential) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - -Fetches the DID Document of the issuer on a `Credential`. - -### Errors - -Errors if the issuer URL is not a valid `DID` or document resolution fails. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| ---------- | -------------------------------------- | -| credential | [Credential](#Credential) | - - - -### resolver.resolvePresentationIssuers(presentation) ⇒ Promise.<Array.<ResolvedDocument>> - -Fetches all DID Documents of `Credential` issuers contained in a `Presentation`. -Issuer documents are returned in arbitrary order. - -### Errors - -Errors if any issuer URL is not a valid `DID` or document resolution fails. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| ------------ | ------------------------------------------ | -| presentation | [Presentation](#Presentation) | - - - -### resolver.resolvePresentationHolder(presentation) ⇒ [Promise.<ResolvedDocument>](#ResolvedDocument) - -Fetches the DID Document of the holder of a `Presentation`. - -### Errors - -Errors if the holder URL is missing, is not a valid `DID`, or document resolution fails. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| ------------ | ------------------------------------------ | -| presentation | [Presentation](#Presentation) | - - - -### resolver.verifyPresentation(presentation, options, fail_fast, holder, issuers) ⇒ Promise.<void> - -Verifies a `Presentation`. - -### Important - -See `PresentationValidator::validate` for information about which properties get -validated and what is expected of the optional arguments `holder` and `issuer`. - -### Resolution - -The DID Documents for the `holder` and `issuers` are optionally resolved if not given. -If you already have up-to-date versions of these DID Documents, you may want -to use `PresentationValidator::validate`. -See also `Resolver::resolvePresentationIssuers` and `Resolver::resolvePresentationHolder`. - -### Errors - -Errors from resolving the holder and issuer DID Documents, if not provided, will be returned immediately. -Otherwise, errors from validating the presentation and its credentials will be returned -according to the `fail_fast` parameter. - -**Kind**: instance method of [Resolver](#Resolver) - -| Param | Type | -| ------------ | ------------------------------------------------------------------------------------------ | -| presentation | [Presentation](#Presentation) | -| options | [PresentationValidationOptions](#PresentationValidationOptions) | -| fail_fast | number | -| holder | [ResolvedDocument](#ResolvedDocument) \| undefined | -| issuers | [Array.<ResolvedDocument>](#ResolvedDocument) \| undefined | - - - -### Resolver.builder() ⇒ [ResolverBuilder](#ResolverBuilder) - -Returns a [ResolverBuilder](#ResolverBuilder) to construct a new `Resolver`. - -**Kind**: static method of [Resolver](#Resolver) - - - -## ResolverBuilder - -Builder for configuring [`Clients`][client] when constructing a [`Resolver`]. - -**Kind**: global class - -- [ResolverBuilder](#ResolverBuilder) - - [new ResolverBuilder()](#new_ResolverBuilder_new) - - [.client(client)](#ResolverBuilder+client) ⇒ [ResolverBuilder](#ResolverBuilder) - - [.clientConfig(config)](#ResolverBuilder+clientConfig) ⇒ [ResolverBuilder](#ResolverBuilder) - - [.build()](#ResolverBuilder+build) ⇒ [Promise.<Resolver>](#Resolver) - - - -### new ResolverBuilder() - -Constructs a new `ResolverBuilder` with no `Clients` configured. - - - -### resolverBuilder.client(client) ⇒ [ResolverBuilder](#ResolverBuilder) - -Inserts a `Client`. - -NOTE: replaces any previous `Client` or `Config` with the same network name. - -**Kind**: instance method of [ResolverBuilder](#ResolverBuilder) - -| Param | Type | -| ------ | ------------------------------ | -| client | [Client](#Client) | - - - -### resolverBuilder.clientConfig(config) ⇒ [ResolverBuilder](#ResolverBuilder) - -Inserts a `Config` used to create a `Client`. - -NOTE: replaces any previous `Client` or `Config` with the same network name. - -**Kind**: instance method of [ResolverBuilder](#ResolverBuilder) - -| Param | Type | -| ------ | -------------------------- | -| config | IClientConfig | - - - -### resolverBuilder.build() ⇒ [Promise.<Resolver>](#Resolver) - -Constructs a new [`Resolver`] based on the builder configuration. - -**Kind**: instance method of [ResolverBuilder](#ResolverBuilder) - - - -## RevocationBitmap - -A compressed bitmap for managing credential revocation. - -**Kind**: global class - -- [RevocationBitmap](#RevocationBitmap) - - [new RevocationBitmap()](#new_RevocationBitmap_new) - - _instance_ - - [.isRevoked(index)](#RevocationBitmap+isRevoked) ⇒ boolean - - [.revoke(index)](#RevocationBitmap+revoke) ⇒ boolean - - [.unrevoke(index)](#RevocationBitmap+unrevoke) ⇒ boolean - - [.len()](#RevocationBitmap+len) ⇒ number - - [.toEndpoint()](#RevocationBitmap+toEndpoint) ⇒ string \| Array.<string> \| Map.<string, Array.<string>> - - _static_ - - [.type()](#RevocationBitmap.type) ⇒ string - - [.fromEndpoint(endpoint)](#RevocationBitmap.fromEndpoint) ⇒ [RevocationBitmap](#RevocationBitmap) - - - -### new RevocationBitmap() - -Creates a new `RevocationBitmap` instance. - - - -### revocationBitmap.isRevoked(index) ⇒ boolean - -Returns `true` if the credential at the given `index` is revoked. - -**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) - -| Param | Type | -| ----- | ------------------- | -| index | number | - - - -### revocationBitmap.revoke(index) ⇒ boolean - -Mark the given index as revoked. - -Returns true if the index was absent from the set. - -**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) - -| Param | Type | -| ----- | ------------------- | -| index | number | - - - -### revocationBitmap.unrevoke(index) ⇒ boolean - -Mark the index as not revoked. - -Returns true if the index was present in the set. - -**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) - -| Param | Type | -| ----- | ------------------- | -| index | number | - - - -### revocationBitmap.len() ⇒ number - -Returns the number of revoked credentials. - -**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) - - - -### revocationBitmap.toEndpoint() ⇒ string \| Array.<string> \| Map.<string, Array.<string>> - -Return the bitmap as a data url embedded in a service endpoint. - -**Kind**: instance method of [RevocationBitmap](#RevocationBitmap) - - - -### RevocationBitmap.type() ⇒ string - -The name of the service type. - -**Kind**: static method of [RevocationBitmap](#RevocationBitmap) - - - -### RevocationBitmap.fromEndpoint(endpoint) ⇒ [RevocationBitmap](#RevocationBitmap) - -Construct a `RevocationBitmap` from a data `url`. - -**Kind**: static method of [RevocationBitmap](#RevocationBitmap) - -| Param | Type | -| -------- | ----------------------------------------------------------------------------------------------------------------- | -| endpoint | string \| Array.<string> \| Map.<string, Array.<string>> | - - - -## Service - -A DID Document Service used to enable trusted interactions associated -with a DID subject. - -See: https://www.w3.org/TR/did-core/#services - -**Kind**: global class - -- [Service](#Service) - - [new Service(service)](#new_Service_new) - - _instance_ - - [.id()](#Service+id) ⇒ [DIDUrl](#DIDUrl) - - [.type()](#Service+type) ⇒ string - - [.serviceEndpoint()](#Service+serviceEndpoint) ⇒ string \| Array.<string> \| Map.<string, Array.<string>> - - [.properties()](#Service+properties) ⇒ Map.<string, any> - - [.toJSON()](#Service+toJSON) ⇒ any - - [.clone()](#Service+clone) ⇒ [Service](#Service) - - _static_ - - [.fromJSON(value)](#Service.fromJSON) ⇒ [Service](#Service) - - - -### new Service(service) - -| Param | Type | -| ------- | --------------------- | -| service | IService | - - - -### service.id() ⇒ [DIDUrl](#DIDUrl) - -Returns a copy of the `Service` id. - -**Kind**: instance method of [Service](#Service) - - - -### service.type() ⇒ string - -Returns a copy of the `Service` type. - -**Kind**: instance method of [Service](#Service) - - - -### service.serviceEndpoint() ⇒ string \| Array.<string> \| Map.<string, Array.<string>> - -Returns a copy of the `Service` endpoint. - -**Kind**: instance method of [Service](#Service) - - - -### service.properties() ⇒ Map.<string, any> - -Returns a copy of the custom properties on the `Service`. - -**Kind**: instance method of [Service](#Service) - - - -### service.toJSON() ⇒ any - -Serializes a `Service` object as a JSON object. - -**Kind**: instance method of [Service](#Service) - - - -### service.clone() ⇒ [Service](#Service) - -Deep clones the object. - -**Kind**: instance method of [Service](#Service) - - - -### Service.fromJSON(value) ⇒ [Service](#Service) - -Deserializes a `Service` object from a JSON object. - -**Kind**: static method of [Service](#Service) - -| Param | Type | -| ----- | ---------------- | -| value | any | - - - -## Signature - -**Kind**: global class - -- [Signature](#Signature) - - [new Signature(data)](#new_Signature_new) - - _instance_ - - [.asBytes()](#Signature+asBytes) ⇒ Uint8Array - - [.toJSON()](#Signature+toJSON) ⇒ any - - _static_ - - [.fromJSON(json_value)](#Signature.fromJSON) ⇒ [Signature](#Signature) - - - -### new Signature(data) - -Creates a new `Signature`. - -| Param | Type | -| ----- | ----------------------- | -| data | Uint8Array | - - - -### signature.asBytes() ⇒ Uint8Array - -Returns a copy of the signature as a `UInt8Array`. - -**Kind**: instance method of [Signature](#Signature) - - - -### signature.toJSON() ⇒ any - -Serializes a `Signature` as a JSON object. - -**Kind**: instance method of [Signature](#Signature) - - - -### Signature.fromJSON(json_value) ⇒ [Signature](#Signature) - -Deserializes a JSON object as `Signature`. - -**Kind**: static method of [Signature](#Signature) - -| Param | Type | -| ---------- | ---------------- | -| json_value | any | - - - -## StorageTestSuite - -A test suite for the `Storage` interface. - -This module contains a set of tests that a correct storage implementation -should pass. Note that not every edge case is tested. - -Tests usually rely on multiple interface methods being implemented, so they should only -be run on a fully implemented version. That's why there is not a single test case for every -interface method. - -**Kind**: global class - -- [StorageTestSuite](#StorageTestSuite) - - [.didCreateGenerateKeyTest(storage)](#StorageTestSuite.didCreateGenerateKeyTest) ⇒ Promise.<void> - - [.didCreatePrivateKeyTest(storage)](#StorageTestSuite.didCreatePrivateKeyTest) ⇒ Promise.<void> - - [.didListTest(storage)](#StorageTestSuite.didListTest) ⇒ Promise.<void> - - [.didPurgeTest(storage)](#StorageTestSuite.didPurgeTest) ⇒ Promise.<void> - - [.keyGenerateTest(storage)](#StorageTestSuite.keyGenerateTest) ⇒ Promise.<void> - - [.keyDeleteTest(storage)](#StorageTestSuite.keyDeleteTest) ⇒ Promise.<void> - - [.keyInsertTest(storage)](#StorageTestSuite.keyInsertTest) ⇒ Promise.<void> - - [.keySignEd25519Test(storage)](#StorageTestSuite.keySignEd25519Test) ⇒ Promise.<void> - - [.encryptionTest(alice_storage, bob_storage)](#StorageTestSuite.encryptionTest) ⇒ Promise.<void> - - - -### StorageTestSuite.didCreateGenerateKeyTest(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.didCreatePrivateKeyTest(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.didListTest(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.didPurgeTest(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.keyGenerateTest(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.keyDeleteTest(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.keyInsertTest(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.keySignEd25519Test(storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------- | -------------------- | -| storage | Storage | - - - -### StorageTestSuite.encryptionTest(alice_storage, bob_storage) ⇒ Promise.<void> - -**Kind**: static method of [StorageTestSuite](#StorageTestSuite) - -| Param | Type | -| ------------- | -------------------- | -| alice_storage | Storage | -| bob_storage | Storage | - - - -## Timestamp - -**Kind**: global class - -- [Timestamp](#Timestamp) - - _instance_ - - [.toRFC3339()](#Timestamp+toRFC3339) ⇒ string - - [.checkedAdd(duration)](#Timestamp+checkedAdd) ⇒ [Timestamp](#Timestamp) \| undefined - - [.checkedSub(duration)](#Timestamp+checkedSub) ⇒ [Timestamp](#Timestamp) \| undefined - - [.toJSON()](#Timestamp+toJSON) ⇒ any - - _static_ - - [.parse(input)](#Timestamp.parse) ⇒ [Timestamp](#Timestamp) - - [.nowUTC()](#Timestamp.nowUTC) ⇒ [Timestamp](#Timestamp) - - [.fromJSON(json)](#Timestamp.fromJSON) ⇒ [Timestamp](#Timestamp) - - - -### timestamp.toRFC3339() ⇒ string - -Returns the `Timestamp` as an RFC 3339 `String`. - -**Kind**: instance method of [Timestamp](#Timestamp) - - - -### timestamp.checkedAdd(duration) ⇒ [Timestamp](#Timestamp) \| undefined - -Computes `self + duration` - -Returns `null` if the operation leads to a timestamp not in the valid range for [RFC 3339](https://tools.ietf.org/html/rfc3339). - -**Kind**: instance method of [Timestamp](#Timestamp) - -| Param | Type | -| -------- | ---------------------------------- | -| duration | [Duration](#Duration) | - - - -### timestamp.checkedSub(duration) ⇒ [Timestamp](#Timestamp) \| undefined - -Computes `self - duration` - -Returns `null` if the operation leads to a timestamp not in the valid range for [RFC 3339](https://tools.ietf.org/html/rfc3339). - -**Kind**: instance method of [Timestamp](#Timestamp) - -| Param | Type | -| -------- | ---------------------------------- | -| duration | [Duration](#Duration) | - - - -### timestamp.toJSON() ⇒ any - -Serializes a `Timestamp` as a JSON object. - -**Kind**: instance method of [Timestamp](#Timestamp) - - - -### Timestamp.parse(input) ⇒ [Timestamp](#Timestamp) - -Parses a `Timestamp` from the provided input string. - -**Kind**: static method of [Timestamp](#Timestamp) - -| Param | Type | -| ----- | ------------------- | -| input | string | - - - -### Timestamp.nowUTC() ⇒ [Timestamp](#Timestamp) - -Creates a new `Timestamp` with the current date and time. - -**Kind**: static method of [Timestamp](#Timestamp) - - - -### Timestamp.fromJSON(json) ⇒ [Timestamp](#Timestamp) - -Deserializes a `Timestamp` from a JSON object. - -**Kind**: static method of [Timestamp](#Timestamp) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## VerificationMethod - -**Kind**: global class - -- [VerificationMethod](#VerificationMethod) - - [new VerificationMethod(did, key_type, public_key, fragment)](#new_VerificationMethod_new) - - _instance_ - - [.id()](#VerificationMethod+id) ⇒ [DIDUrl](#DIDUrl) - - [.controller()](#VerificationMethod+controller) ⇒ [DID](#DID) - - [.SetController(did)](#VerificationMethod+SetController) - - [.type()](#VerificationMethod+type) ⇒ [MethodType](#MethodType) - - [.data()](#VerificationMethod+data) ⇒ [MethodData](#MethodData) - - [.toJSON()](#VerificationMethod+toJSON) ⇒ any - - [.clone()](#VerificationMethod+clone) ⇒ [VerificationMethod](#VerificationMethod) - - _static_ - - [.fromJSON(value)](#VerificationMethod.fromJSON) ⇒ [VerificationMethod](#VerificationMethod) - - - -### new VerificationMethod(did, key_type, public_key, fragment) - -Creates a new `VerificationMethod` object from the given `did` and public key. - -| Param | Type | -| ---------- | ------------------------ | -| did | [DID](#DID) | -| key_type | number | -| public_key | Uint8Array | -| fragment | string | - - - -### verificationMethod.id() ⇒ [DIDUrl](#DIDUrl) - -Returns a copy of the `id` `DIDUrl` of the `VerificationMethod` object. - -**Kind**: instance method of [VerificationMethod](#VerificationMethod) - - - -### verificationMethod.controller() ⇒ [DID](#DID) - -Returns a copy of the `controller` `DID` of the `VerificationMethod` object. - -**Kind**: instance method of [VerificationMethod](#VerificationMethod) - - - -### verificationMethod.SetController(did) - -Sets the `controller` `DID` of the `VerificationMethod` object. - -**Kind**: instance method of [VerificationMethod](#VerificationMethod) - -| Param | Type | -| ----- | ------------------------ | -| did | [DID](#DID) | - - - -### verificationMethod.type() ⇒ [MethodType](#MethodType) - -Returns a copy of the `VerificationMethod` type. - -**Kind**: instance method of [VerificationMethod](#VerificationMethod) - - - -### verificationMethod.data() ⇒ [MethodData](#MethodData) - -Returns a copy of the `VerificationMethod` public key data. - -**Kind**: instance method of [VerificationMethod](#VerificationMethod) - - - -### verificationMethod.toJSON() ⇒ any - -Serializes a `VerificationMethod` object as a JSON object. - -**Kind**: instance method of [VerificationMethod](#VerificationMethod) - - - -### verificationMethod.clone() ⇒ [VerificationMethod](#VerificationMethod) - -Deep clones the object. - -**Kind**: instance method of [VerificationMethod](#VerificationMethod) - - - -### VerificationMethod.fromJSON(value) ⇒ [VerificationMethod](#VerificationMethod) - -Deserializes a `VerificationMethod` object from a JSON object. - -**Kind**: static method of [VerificationMethod](#VerificationMethod) - -| Param | Type | -| ----- | ---------------- | -| value | any | - - - -## VerifierOptions - -Holds additional proof verification options. -See `IVerifierOptions`. - -**Kind**: global class - -- [VerifierOptions](#VerifierOptions) - - [new VerifierOptions(options)](#new_VerifierOptions_new) - - _instance_ - - [.toJSON()](#VerifierOptions+toJSON) ⇒ any - - [.clone()](#VerifierOptions+clone) ⇒ [VerifierOptions](#VerifierOptions) - - _static_ - - [.default()](#VerifierOptions.default) ⇒ [VerifierOptions](#VerifierOptions) - - [.fromJSON(json)](#VerifierOptions.fromJSON) ⇒ [VerifierOptions](#VerifierOptions) - - - -### new VerifierOptions(options) - -Creates a new `VerifierOptions` from the given fields. - -Throws an error if any of the options are invalid. - -| Param | Type | -| ------- | ----------------------------- | -| options | IVerifierOptions | - - - -### verifierOptions.toJSON() ⇒ any - -Serializes a `VerifierOptions` as a JSON object. - -**Kind**: instance method of [VerifierOptions](#VerifierOptions) - - - -### verifierOptions.clone() ⇒ [VerifierOptions](#VerifierOptions) - -Deep clones the object. - -**Kind**: instance method of [VerifierOptions](#VerifierOptions) - - - -### VerifierOptions.default() ⇒ [VerifierOptions](#VerifierOptions) - -Creates a new `VerifierOptions` with default options. - -**Kind**: static method of [VerifierOptions](#VerifierOptions) - - - -### VerifierOptions.fromJSON(json) ⇒ [VerifierOptions](#VerifierOptions) - -Deserializes a `VerifierOptions` from a JSON object. - -**Kind**: static method of [VerifierOptions](#VerifierOptions) - -| Param | Type | -| ----- | ---------------- | -| json | any | - - - -## X25519 - -An implementation of `X25519` Elliptic-curve Diffie-Hellman (ECDH) cryptographic key exchange. - -**Kind**: global class - -- [X25519](#X25519) - - [.PRIVATE_KEY_LENGTH()](#X25519.PRIVATE_KEY_LENGTH) ⇒ number - - [.PUBLIC_KEY_LENGTH()](#X25519.PUBLIC_KEY_LENGTH) ⇒ number - - [.keyExchange(privateKey, publicKey)](#X25519.keyExchange) ⇒ Uint8Array - - [.Ed25519toX25519Private(privateKey)](#X25519.Ed25519toX25519Private) ⇒ Uint8Array - - [.Ed25519toX25519Public(publicKey)](#X25519.Ed25519toX25519Public) ⇒ Uint8Array - - - -### X25519.PRIVATE_KEY_LENGTH() ⇒ number - -Length in bytes of an X25519 private key. - -**Kind**: static method of [X25519](#X25519) - - - -### X25519.PUBLIC_KEY_LENGTH() ⇒ number - -Length in bytes of an X25519 public key. - -**Kind**: static method of [X25519](#X25519) - - - -### X25519.keyExchange(privateKey, publicKey) ⇒ Uint8Array - -Performs Diffie-Hellman key exchange using the private key of the first party with the -public key of the second party, resulting in a shared secret. - -**Kind**: static method of [X25519](#X25519) - -| Param | Type | -| ---------- | ----------------------- | -| privateKey | Uint8Array | -| publicKey | Uint8Array | - - - -### X25519.Ed25519toX25519Private(privateKey) ⇒ Uint8Array - -Transforms an `Ed25519` private key to an `X25519` private key. - -This is possible because Ed25519 is birationally equivalent to Curve25519 used by X25519. - -**Kind**: static method of [X25519](#X25519) - -| Param | Type | -| ---------- | ----------------------- | -| privateKey | Uint8Array | - - - -### X25519.Ed25519toX25519Public(publicKey) ⇒ Uint8Array - -Transforms an `Ed25519` public key to an `X25519` public key. - -This is possible because Ed25519 is birationally equivalent to Curve25519 used by X25519. - -**Kind**: static method of [X25519](#X25519) - -| Param | Type | -| --------- | ----------------------- | -| publicKey | Uint8Array | - - - -## DIDMessageEncoding - -**Kind**: global variable - - - -## StatusCheck - -Controls validation behaviour when checking whether or not a credential has been revoked by its -[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status). - -**Kind**: global variable - - - -## Strict - -Validate the status if supported, reject any unsupported -[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) types. - -Only `RevocationBitmap2022` is currently supported. - -This is the default. - -**Kind**: global variable - - - -## SkipUnsupported - -Validate the status if supported, skip any unsupported -[`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) types. - -**Kind**: global variable - - - -## SkipAll - -Skip all status checks. - -**Kind**: global variable - - - -## SubjectHolderRelationship - -Declares how credential subjects must relate to the presentation holder during validation. -See `PresentationValidationOptions::subject_holder_relationship`. - -See also the [Subject-Holder Relationship](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships) section of the specification. - -**Kind**: global variable - - - -## AlwaysSubject - -The holder must always match the subject on all credentials, regardless of their [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property. -This variant is the default used if no other variant is specified when constructing a new -`PresentationValidationOptions`. - -**Kind**: global variable - - - -## SubjectOnNonTransferable - -The holder must match the subject only for credentials where the [`nonTransferable`](https://www.w3.org/TR/vc-data-model/#nontransferable-property) property is `true`. - -**Kind**: global variable - - - -## Any - -The holder is not required to have any kind of relationship to any credential subject. - -**Kind**: global variable - - - -## FailFast - -Declares when validation should return if an error occurs. - -**Kind**: global variable - - - -## AllErrors - -Return all errors that occur during validation. - -**Kind**: global variable - - - -## FirstError - -Return after the first error occurs. - -**Kind**: global variable - - - -## KeyType - -**Kind**: global variable - - - -## MethodRelationship - -**Kind**: global variable - - - -## start() - -Initializes the console error panic hook for better error messages - -**Kind**: global function diff --git a/docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx b/docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx deleted file mode 100644 index ed745a94422..00000000000 --- a/docs/build/identity.rs/0.6/docs/libraries/wasm/getting_started.mdx +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: Getting Started with WASM -sidebar_label: Getting Started -description: Getting started with the IOTA Identity WASM Library. -image: /img/Identity_icon.png -keywords: - - WASM - - install - - npm - - yarn - - build - - nodejs - - webpack ---- - -# IOTA Identity WASM - -> This is the beta version of the official WASM bindings for [IOTA Identity](https://github.com/iotaledger/identity.rs). - -## [API Reference](./api_reference.mdx) - -## [Account Examples](https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples-account/README.md) - -## [Low-Level Examples](https://github.com/iotaledger/identity.rs/blob/support/v0.6/bindings/wasm/examples/README.md) - -## Install the library - -Latest Release: this version matches the main branch of this repository, is stable and will have changelogs. - -```bash -npm install @iota/identity-wasm -``` - -Development Release: this version matches the dev branch of this repository, may see frequent breaking changes and has the latest code changes. - -```bash -npm install @iota/identity-wasm@dev -``` - -## Build - -Alternatively, you can build the bindings if you have Rust installed. If not, refer to [rustup.rs](https://rustup.rs) for the installation. - -Install [`wasm-bindgen-cli`](https://github.com/rustwasm/wasm-bindgen). A manual installation is required because we use the [Weak References](https://rustwasm.github.io/wasm-bindgen/reference/weak-references.html) feature, which [`wasm-pack` does not expose](https://github.com/rustwasm/wasm-pack/issues/930). - -```bash -cargo install --force wasm-bindgen-cli -``` - -Then, install the necessary dependencies using: - -```bash -npm install -``` - -and build the bindings for `node.js` with - -```bash -npm run build:nodejs -``` - -or for the `web` with - -```bash -npm run build:web -``` - -## Minimum Requirements - -The minimum supported version for node is: `v16.0.0` - -## NodeJS Usage - - - - -```javascript -const identity = require('@iota/identity-wasm/node'); - -async function main() { - // The creation step generates a keypair, builds an identity - // and publishes it to the IOTA mainnet. - const builder = new identity.AccountBuilder(); - const account = await builder.createIdentity(); - - // Retrieve the DID of the newly created identity. - const did = account.did(); - - // Print the DID of the created Identity. - console.log(did.toString()); - - // Print the local state of the DID Document - console.log(account.document()); - - // Print the Explorer URL for the DID. - console.log(`Explorer Url:`, identity.ExplorerUrl.mainnet().resolverUrl(did)); -} - -main(); -``` - -## Web Setup - -The library loads the WASM file with an HTTP GET request, so the .wasm file must be copied to the root of the dist folder. - -### Rollup - -- Install `rollup-plugin-copy`: - -```bash -npm install rollup-plugin-copy --save-dev -``` - -- Add the copy plugin usage to the `plugins` array under `rollup.config.js`: - -```js -// Include the copy plugin -import copy from 'rollup-plugin-copy'; - -// Add the copy plugin to the `plugins` array of your rollup config: -copy({ - targets: [ - { - src: 'node_modules/@iota/identity-wasm/web/identity_wasm_bg.wasm', - dest: 'public', - rename: 'identity_wasm_bg.wasm', - }, - ], -}); -``` - -### Webpack - -- Install `copy-webpack-plugin`: - -```bash -npm install copy-webpack-plugin --save-dev -``` - -```js -// Include the copy plugin -const CopyWebPlugin= require('copy-webpack-plugin'); - -// Add the copy plugin to the `plugins` array of your webpack config: - -new CopyWebPlugin({ - patterns: [ - { - from: 'node_modules/@iota/identity-wasm/web/identity_wasm_bg.wasm', - to: 'identity_wasm_bg.wasm' - } - ] -}), -``` - -### Web Usage - -```js -import * as identity from "@iota/identity-wasm/web"; - -identity.init().then(() => { - - // The creation step generates a keypair, builds an identity - // and publishes it to the IOTA mainnet. - let builder = new identity.AccountBuilder(); - let account = await builder.createIdentity(); - - // Retrieve the DID of the newly created identity. - const did = account.did(); - - // Print the DID of the created Identity. - console.log(did.toString()) - - // Print the local state of the DID Document - console.log(account.document()); - -}); - -// or - -(async () => { - - await identity.init() - - // The creation step generates a keypair, builds an identity - // and publishes it to the IOTA mainnet. - let builder = new identity.AccountBuilder(); - let account = await builder.createIdentity(); - - // Retrieve the DID of the newly created identity. - const did = account.did(); - - // Print the DID of the created Identity. - console.log(did.toString()) - - // Print the local state of the DID Document - console.log(account.document()); - -})() - -// Default path is "identity_wasm_bg.wasm", but you can override it like this -await identity.init("./static/identity_wasm_bg.wasm"); -``` - -`identity.init().then()` or `await identity.init()` is required to load the wasm file (from the server if not available, because of that it will only be slow for the first time) - -## Examples in the Wild - -You may find it useful to see how the WASM bindings are being used in existing applications: - -- [Zebra IOTA Edge SDK](https://github.com/ZebraDevs/Zebra-Iota-Edge-SDK) (mobile apps using Capacitor.js + Svelte) diff --git a/docs/build/identity.rs/0.6/docs/specs/did/iota_did_method_spec.mdx b/docs/build/identity.rs/0.6/docs/specs/did/iota_did_method_spec.mdx deleted file mode 100644 index 1442413cb91..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/did/iota_did_method_spec.mdx +++ /dev/null @@ -1,375 +0,0 @@ ---- -title: IOTA DID Method Specification -sidebar_label: DID Method -description: How IOTA Identity implements the Decentralized Identifiers Standard on the IOTA Tangle. -image: /img/Identity_icon.png -keywords: - - DID - - specs - - specifications - - Decentralized Identifiers - - Tangle - - format ---- - -# IOTA DID Method Specification - -Version 0.5-draft by Jelle Millenaar, IOTA Foundation - -## Abstract - -The IOTA DID Method Specification describes a method of implementing the [Decentralized Identifiers](https://www.w3.org/TR/did-core/) (DID) standard on the [IOTA Tangle](https://iota.org), a Distributed Ledger Technology (DLT). It conforms to the [DID specifications v1.0 Working Draft 20200731](https://www.w3.org/TR/2020/WD-did-core-20200731/) and describes how to publish DID Document Create, Read, Update and Delete (CRUD) operations to the IOTA Tangle. In addition, it lists additional non-standardized features that are built for the IOTA Identity implementation. - -## Introduction - -### The IOTA Tangle - -This specification defines a method of implementing DID on top of the [IOTA Tangle](https://iota.org), which is a Distributed Ledger Technology (DLT) using a Tangle data structure. In contrast to a Blockchain, the Tangle does not store messages in blocks and chain them together, but rather creates a data structure where a message references between one and eight previous messages (used to be two, as the gif shows), creating a parallel structure. - -| Blockchain | Tangle | -| :--------: | :----: | - -![Blockchain bottleneck](/img/blockchain-bottleneck.gif) | ![Tangle Bottleneck](/img/tangle-bottleneck.gif) - -For this method, the most important features of IOTA are: - -- The lack of fees, requiring no cryptocurrency tokens to be owned in order to submit a message to the DLT. -- The DLT has a public and permissionless network which runs the IOTA cryptocurrency. -- Pure data messages are possible to be stored immutably. -- Few nodes store the entire Tangle, requiring additional logic to prove the immutability of data. - -## DID Method Name - -The namestring to identify this DID method is: `iota`. - -A DID that uses this method MUST begin with the following prefix: `did:iota`. Following the generic DID specification, this string MUST be lowercase. - -## DID Format - -The DIDs that follow this method have the following format: - -``` -iota-did = "did:iota:" iota-specific-idstring -iota-specific-idstring = [ iota-network ":" ] iota-tag -iota-network = char{,6} -iota-tag = base-char{44} -char = 0-9 a-z -base-char = 1-9 A-H J-N P-Z a-k m-z -``` - -### IOTA-Network - -The iota-network is an identifier of the network where the DID is stored. This network must be an IOTA Tangle, but can either be a public or private network, permissionless or permissioned. - -The following values are reserved and cannot reference other networks: - -1. `main` references the main network which refers to the Tangle known to host the IOTA cryptocurrency. -2. `dev` references the development network known as "devnet" maintained by the IOTA Foundation. - -When no IOTA network is specified, it is assumed that the DID is located on the `main` network. This means that the following DIDs will resolve to the same DID Document: - -``` -did:iota:main:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV -did:iota:H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV -``` - -### IOTA-Tag - -The IOTA tag references an indexation which resolves to the initial DID Messages. - -#### Generation - -The following steps MUST be taken to generate a valid tag: - -- Generate an asymmetric keypair using a supported verification method type. -- Hash the public key using `BLAKE2b-256` then encode it using [Base58-BTC](https://tools.ietf.org/id/draft-msporny-base58-01.html). - -This public key MUST be embedded into the DID Document (see [CRUD: Create](#create)). - -## DID Messages - -DID Documents associated with the `did:iota` method consist of a chain of data messages, called "DID messages", published to a Tangle. The Tangle has no understanding of DID messages and acts purely as an immutable database. The chain of DID messages and the resulting DID Document must therefore be validated on the client side. - -A DID message can be part of one of two different message chains, the "Integration Chain" (Int Chain) and the "Differentiation Chain" (Diff Chain). The Integration Chain is a chain of "Integration DID Messages" that contain JSON formatted DID Documents as per the W3C standard for DID. The Diff Chain is a chain of "DID Diff Messages" that contain JSON objects which only list the differences between the previous DID Document and the next state. - -### Previous Message Id - -All DID message uploaded to the Tangle, with the exception of the very first DID message that creates the DID, MUST contain a `previousMessageId` field. This field MUST carry the MessageId, an IOTA indexation for a single message, of the previous DID Document that is updated with this DID message. This value SHOULD be used to order DID messages during the resolving procedure. If two or more DID messages reference the same `previousMessageId` an ordering conflict is identified and is resolved using a [deterministic ordering mechanism](#determining-order). - -Example of an IOTA MessageId: - -```json -"previousMessageId": "cd8bb7baca6bbfa1de7813bd1753a2de026b6ec75dba8a3cf32c0d4cf6038917" -``` - -### Signing Keys - -DID messages published to the Tangle must be cryptographically signed. As such, the DID Document MUST include at least one public key with a [capability invocation relationship](https://www.w3.org/TR/did-core/#capability-invocation). Only verification methods with a [capability invocation relationship](https://www.w3.org/TR/did-core/#capability-invocation) are allowed to sign IOTA DID Document updates. It is recommended, for security reasons, not to use signing keys for other purposes as control over them is vital for controlling the identity. It is RECOMMENDED to name the initial verification method `#sign-x`, where `x` is the index of the signing key, which is incremented every time the signing key is updated, starting at index 1. - -The initial DID message containing a newly-generated DID Document MUST be signed with the same keypair used to derive its [IOTA-Tag](#iota-tag) (see [CRUD: Create](#create)). - -See [Standardized Verification Method Types](#standardized-verification-method-types) for which cryptographic key types are supported. - -### Anatomy of Integration DID Messages - -An Integration (Int) DID message MUST contain both a valid DID Document and a [DID Document Metadata](https://www.w3.org/TR/did-core/#did-document-metadata) according to the W3C DID standard. In addition, the message has further restrictions: - -- The DID Document MUST contain one or more verification methods capable of signing updates as defined in the [Signing Keys](#signing-keys) section. -- The first DID Document in the chain MUST contain a `verificationMethod` that contains a public key that, when hashed using the `Blake2b-256` hashing function, equals the tag section of the DID. This prevents the creation of conflicting entry messages of the chain by adversaries. -- An Integration DID message must be published to an IOTA Tangle on an index that is generated by the `BLAKE2b-256` of the public key, created in the [generation](#generation) event, encoded in `hex`. -- Integration DID messages SHOULD contain all cumulative changes from the Diff Chain associated to the last Integration Chain message. Any changes added in the Diff Chain that are not added to the new Integration DID message will be lost. -- The DID Document Metadata MUST include a `previousMessageId` attribute. This field provides an immutable link to the previous integration DID message that is used for basic ordering of the DID messages, creating a chain. The value of `previousMessageId` MUST be a string that contains an IOTA MessageId from the previous DID message it updates, which MUST reference an integration DID message. The field SHOULD be omitted if the DID message is the start of the Int chain, otherwise the field is REQUIRED. Read the [Previous Message Id](#previous-message-id) section for more information. -- The DID Document MUST include a `proof` attribute. This field provides a cryptographic proof on the message that proves ownership over the DID Document. The value of the `proof` object MUST contain an object as defined by [Anatomy of the Proof object](#anatomy-of-the-proof-object). - -Example of an Integration DID Message: - -```json -{ - "doc": { - "id": "did:iota:ERtmNv3hYnWU7fZMGKpMLy7QBJqPovCSYyewtoHUGmpf", - "capabilityInvocation": [ - { - "id": "did:iota:ERtmNv3hYnWU7fZMGKpMLy7QBJqPovCSYyewtoHUGmpf#sign-0", - "controller": "did:iota:ERtmNv3hYnWU7fZMGKpMLy7QBJqPovCSYyewtoHUGmpf", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "zETX79R6G5fkTMZhHXaCMhjC3Xpx3NLJVSNurat8Ls9Tn" - } - ] - }, - "meta": { - "created": "2022-03-18T06:59:50Z", - "updated": "2022-03-18T06:59:50Z" - }, - "proof": { - "type": "JcsEd25519Signature2020", - "verificationMethod": "did:iota:ERtmNv3hYnWU7fZMGKpMLy7QBJqPovCSYyewtoHUGmpf#sign-0", - "signatureValue": "278R6WyoG359VjnGm2GJK6XAjBNh6AM59BXJmjfRQerVQMTG3EjWGXw64CKgGKvVBbP98QMVUw1YXBbuGuDbJW6A" - } -} -``` - -### Anatomy of Diff DID Messages - -A Differentiation (Diff) DID message does not contain a valid DID Document. Instead, the chain creates a list of incremental changes compared to the Integration DID message that is used as a basis. The Diff DID messages are hosted on a different index on the Tangle, which allows skipping older Diff DID messages during a query, optimizing the client verification speed significantly. - -- A Diff DID message is NOT allowed to add, remove or update any [signing keys](#signing-keys). This must be done via an Integration DID message. -- A Diff DID message must be published to an IOTA Tangle on an index that is generated by the hash, generated by the `BLAKE2b-256` hashing algorithm, of the `previousMessageId` of the latest Integration DID message and encoded in `hex`. -- A Diff DID message MUST have at least the following attributes: - - `id` (REQUIRED): This field helps link the update to a DID. The value of `id` MUST be a string that references the DID that this update applies to. - - `previousMessageId` (REQUIRED): This field provides an immutable link to the previous DID document that is updated and is used for basic ordering of the DID messages, creating a chain. The value of `previousMessageId` MUST be a string that contains an IOTA MessageId from the previous DID message it updates, which references either a Diff or Int Chain message. Read the [Previous Message Id](#previous-message-id) section for more information. - - `diff` (REQUIRED): A Differentiation object containing all the changes compared to the DID Document it references in the `previousMessageId` field. The value of `diff` MUST be a JSON object following the [Anatomy of the Diff object](#anatomy-of-the-diff-object) definition. - - `proof` (REQUIRED): This field provides a cryptographic proof on the message that proves ownership over the DID Document. The value of the `proof` object MUST contain an object as defined by [Anatomy of the Proof object](#anatomy-of-the-proof-object). - -Example of a Diff DID message: - -```json -{ - "id": "did:iota:X7U84ez4YeaLwpfdnhdgFyPLa53twvAuMSYdRQas54e", - "diff": { - "doc": { - "service": [ - { - "id": "did:iota:X7U84ez4YeaLwpfdnhdgFyPLa53twvAuMSYdRQas54e#linked-domain-1", - "type_": "LinkedDomains", - "service_endpoint": "https://example.com/" - } - ] - }, - "meta": { - "updated": "2022-01-21T09:50:28Z" - } - }, - "previousMessageId": "5dfff82c34c75b3436e7e03370e220e4693d39026fee315e6db7b7815305df4a", - "proof": { - "type": "JcsEd25519Signature2020", - "verificationMethod": "#sign-0", - "signatureValue": "3TG8LiXbWPcH3ecg4is5mswENVuQBakhv8R5TMXopHgPg578oLoczySvZMsEdjRHYgJGihK2VHEqyCHPjQyXW61m" - } -} -``` - -### Anatomy of the Proof object - -Following the proof format in the [Verifiable Credential standard](https://www.w3.org/TR/vc-data-model/#proofs-signatures), at least one proof mechanism, and the details necessary to evaluate that, MUST be expressed for a DID Document uploaded to the Tangle. - -The proof object is an embedded proof that contains all information to be verifiable. It contains one or more cryptographic proofs that can be used to detect tampering and verify the authorship of a DID creation or update. It mostly follows LD-Proofs standard. - -**Type** - -The proof object MUST include a `type` property. This property references a verification method type's signature algorithm, as standardized in the [DID spec registries](https://www.w3.org/TR/did-spec-registries/#verification-method-types) or standardized via the method specification. - -The IOTA Identity implementation currently supports: - -- `JcsEd25519Signature2020` - -It must be emphasized that the IOTA Identity implementation of `JcsEd25519Signature2020` follows the [official specification](https://identity.foundation/JcsEd25519Signature2020/) with the single exception that the SHA-256 pre-hash of the input, the third step of the [proof generation algorithm](https://identity.foundation/JcsEd25519Signature2020/#ProofGeneration), is skipped. See the following two GitHub issues [#22](https://github.com/decentralized-identity/JcsEd25519Signature2020/issues/22) and [#26](https://github.com/decentralized-identity/JcsEd25519Signature2020/issues/26) for more context on why this deviation is deemed necessary. - -**Verification Method** - -The proof object MUST include a `verificationMethod` which references a verification method embedded in the same DID Document. The verification method must be capable of signing DID messages as per the [Signing Keys](#signing-keys) section. - -**Signature** - -Depending on the verification method, a set of fields are REQUIRED to provide the cryptographic proof of the DID Document. For example, the `JcsEd25519Signature2020` method has a `signatureValue` field. - -Example `proof` using the `JcsEd25519Signature2020` method: - -```json -"proof": { - "type": "JcsEd25519Signature2020", - "verificationMethod": "did:iota:GzXeqBXGCbuebiFtKo4JDNo6CmYmGbqxyh2fDVKadiBG#authentication", - "signatureValue": "3fLtv3KUU4T5bHNLprV3UQ2Te3bcRZ9uUYSFouEA7fmYthieV35NNLqbKUu8t2QmzYgnfp1KMzCqPzGNi3RjU822" -} -``` - -### Anatomy of the Diff object - -The `diff` object MUST contain all the differences between the current and previous DID Document and its DID Document Metadata. The differentiation is formatted as a JSON object that includes the differences between the two DID Document objects and the two DID Document Metadata objects. Exact details of how this is generated will be added later. - -Example `diff` of adding a new service entry to the document and changing the `updated` field in the metadata: - -```json -{ - "diff": { - "doc": { - "service": [ - { - "id": "did:iota:X7U84ez4YeaLwpfdnhdgFyPLa53twvAuMSYdRQas54e#linked-domain-1", - "type_": "LinkedDomains", - "service_endpoint": "https://example.com/" - } - ] - }, - "meta": { - "updated": "2022-01-21T09:50:28Z" - } - } -} -``` - -## CRUD Operations - -Create, Read, Update and Delete (CRUD) operations that change the DID Documents are to be submitted to an IOTA Tangle in order to be publicly available. They will either have to be a valid Int DID message or Diff DID message, submitted on the correct index of the identity. - -### Create - -To generate a new DID, the method described in [generation](#generation) must be followed. A basic DID Document must be created that includes the public key used in the DID creation process as a `verificationMethod` with a capability invocation verification relationship. This DID Document must be formatted as an Integration DID message, signed using the same keypair used to generate the tag, and published to an IOTA Tangle on the index generated out of the public key used in the DID creation process. - -### Read - -To read the latest DID Document associated with a DID, the following steps are to be performed: - -1. Query all the Integration DID messages from the index, which is the `tag` part of the DID. -2. Order the messages based on `previousMessageId` linkages. See [Determining Order](#determining-order) for more details. -3. Validate the first Integration DID message containing a verification method with a public key that, when hashed using the `BLAKE2b-256` hashing algorithm, equals the `tag` field of the DID as per [generation](#generation). This first Integration DID message MUST also contain a valid signature referencing the same verification method. -4. Verify the signatures of all the DID messages. Signatures must be created using a public key available in the previous DID message linked to a verification method capable of signing DID messages. See [Signing Keys](#signing-keys). -5. Ignore any messages that are not signed correctly, afterwards ignore any messages that are not first in the ordering for their specific location in the chain. -6. Query all the Diff DID messages from the index, generated by the MessageId from the last valid Integration DID message, hashed using `Blake2b-256` and encoded in `hex`. -7. Order messages and validate signatures in a similar manner to steps 2, 4 and 5 above. The first valid Diff DID message MUST have a `previousMessageId` referencing the `messageId` of the last Integration DID message. -8. Ignore Diff DID messages with illegal operations such as removing or updating a signing key. -9. Apply all valid Diff updates to the state generated from the Integration DID messages. This will result in the latest DID Document. - -#### Determining Order - -To determine the order of any DID messages, the following steps are to be performed: - -1. Order is initially established by recreating the chain based on the `previousMessageId` linkages. - 1. For Int DID messages, the one with no `previousMessageId` is first. - 2. For Diff DID messages, the one with a `previousMessageId` referencing the IOTA MessageId of the corresponding Integration DID message is first. -2. When two or more Messages compete, an order must be established between them. -3. To determine the order, check which milestone confirmed the messages. -4. If multiple messages are confirmed by the same milestone, we order based on the IOTA MessageId with alphabetical ordering. - -### Update - -In order to update a DID Document, either an Integration or a Diff DID message needs to be generated. It is RECOMMENDED to use only Integration DID messages if the DID Document is updated very infrequently and it is expected to never go beyond 100 updates in the lifetime of the DID. If that is not the case, it is RECOMMENDED to use as many Diff DID messages instead with a maximum of around 100 updates per Diff chain. - -#### Creating an Integration DID message - -An Integration DID message is unrestricted in its operations and may add or remove any fields to the DID Document. In order to query the DID Document, every Integration DID message must be processed, therefore it is RECOMMENDED to reduce the usage of these messages unless the DID Document is updated very infrequently. - -In order to create a valid Integration DID message, the following steps are to be performed: - -1. Create a new DID Document that contains all the new target state. This SHOULD include the new desired changes and all the changes inside the previous Diff Chain, otherwise these changes are lost! -2. Retrieve the IOTA MessageId from the previous Integration DID message and a keypair for signing the DID Document. -3. Set the `previousMessageId` field to the IOTA MessageId value. -4. Create a `proof` object referencing the public key and signature suite from a verification method in the DID Document able to sign updates as per the [Signing Keys](#signing-keys) section. -5. Create a cryptographic signature using the same keypair and add the result to the appropriate field(s) inside the `proof` object. - -#### Creating a Diff DID message - -A Differentiation DID message is restricted in its usage. It may not update any signing keys that are used in the Diff chain. If this is desired, it is REQUIRED to use an Integration DID message. If the current Diff chain becomes too long (currently RECOMMENDED to end at a length of 100), it is RECOMMENDED to use a single Integration DID message to reset its length. - -In order to create a valid Integration DID message, the following steps are to be performed: - -1. Create and serialize a `diff` JSON object that contains all the changes. -2. Set the `did` field to the DID value that this update applies to. -3. Retrieve the IOTA MessageId from the previous Diff chain message, or Integration DID message if this message is the first in the Diff chain. In addition, retrieve a keypair for signing the DID Document. -4. Set the `previousMessageId` field to the IOTA MessageId value. -5. Create a `proof` object referencing the public key and signature suite from a verification method in the DID Document able to sign updates as per the [Signing Keys](#signing-keys) section. -6. Create a cryptographic signature using the same keypair and add the result to the appropriate field(s) inside the `proof` object. - -### Delete - -In order to deactivate a DID document, a valid Integration DID message must be published that removes all content from a DID Document, effectively deactivating the DID Document. Keep in mind that this operation is irreversible. - -## IOTA Identity standards - -The `did:iota` method is implemented in the [IOTA Identity framework](https://github.com/iotaledger/identity.rs). This framework supports a number of operations that are standardized, some are standardized across the SSI community, and some are the invention of the IOTA Foundation. - -### Standardized Verification Method Types - -The IOTA Identity framework currently supports two Verification Method Types: - -- `Ed25519VerificationKey2018`: can be used to sign DID Document updates, Verifiable Credentials, Verifiable Presentations, and arbitrary data with a `JcsEd25519Signature2020`. -- `X25519KeyAgreementKey2019`: can be used to perform [Diffie-Hellman key exchange](https://en.wikipedia.org/wiki/Diffie%E2%80%93Hellman_key_exchange) operations to derive a shared secret between two parties. - -### Revocation - -Revocation of Verifiable Credentials and signatures is currently achieved through revoking public keys in the IOTA Identity framework. Alternatively, developers should consider using the [`credentialStatus` property](https://www.w3.org/TR/vc-data-model/#status) when issuing and revoking Verifiable Credentials at scale. - -### Standardized Services - -The IOTA Identity framework also standardized certain `services` that are embedded in the DID Document. It is RECOMMENDED to implement these when implementing the `did:iota` method. - -Currently standardized `services`: - -- Nothing yet. - -## Security Considerations - -The `did:iota` method is implemented on the [IOTA Tangle](https://iota.org), a public permissionless and feeless Distributed Ledger Technology (DLT), making it resistant against almost all censorship attack vectors. Up until the `Coordicide` update for the IOTA network, a reliability on the _coordinator_ exists for resolving ordering conflicts. This has a minor censorship possibility, that, in the worst case, can prevent ordering conflicts from resolving to a DID. However, these can only be published by the owner of the private key and therefore does not constitute a usable attack vector. Lastly, a node may decide to censor DID messages locally, however a user can easily use another node. - -Since DID messages are always to be signed and the 'chain of custody' of the signing key can be traced throughout the identity lifespan, replay, message insertion, deletion, modification and man-in-the-middle attacks are prevented. - -### Stateless Identities - -Unlike for-purpose blockchains or Smart Contract based DID methods, the IOTA Tangle does not track and store the state of DID Document. This prevents dusting attacks against the nodes. However, the client that resolves the DID Document has the responsibility to always validate the entire history of the DID Document as to validate the 'chain of custody' of the signing keys. If a client does not do this, identity hijacking is trivially possible. The IOTA Identity framework, which implements the `did:iota` method, provides an easy-to-use client-side validation implementation. - -### Snapshotting - -IOTA allows feeless data and value messages. As such, it has a large history of messages amounting to several TBs at the time of writing. Most nodes 'snapshot' (forget/delete) older transactions, while they keep the UTXOs stored in the ledger. The snapshot settings are local, therefore all nodes may store a different length of history. As such, older DID messages would not be available at every node. Since the entire history of the DID Document is required for client-side validation, this may become problematic. It is currently recommended to either use your own node that does not snapshot, or use the [Chronicle Permanode](https://github.com/iotaledger/chronicle.rs), which keeps the entire history of the Tangle. This is not a longterm scalable solution, which is why other methods for either keeping state or selective storage are considered. - -### Denial of Service Attacks - -There is little to no barrier for users to send any message to the Tangle. While this is a great feature of IOTA, it has its drawbacks in terms of spam. Anyone can post messages on the index of an Identity and therefore decrease the query speed. To reduce a user's own load on their identity verification speed, the Diff chain was introduced. Other messages that are spammed are identified and dropped as early as possible in the resolution process without triggering any errors or warnings. These are, for example, random data messages or incorrectly signed DID messages. - -IOTA nodes provide pagination for more then 100 messages on an index, requiring multiple queries for identities with more messages. Since the queries are the bottleneck in the resolution process, it is recommended to run an IOTA node in a nearby location if fast verification is required for the use case. Verification may, in the future, also be outsourced to nodes directly, to reduce the effect of spam attacks. If an identity is significantly spammed, it might be best to create a new identity. - -### Quantum Computer Threats - -The `did:iota` method is no more vulnerable to quantum computers than other DID methods. The IOTA Identity framework currently utilizes elliptic curve based cryptographic suites, however adding support for quantum secure cryptographic suites in the future is very easy. - -### Private Key Management - -All private keys or seeds used for the `did:iota` method should be equally well protected by the users. The signing key is especially important as it controls how keys are added or removed, providing full control over the identity. The IOTA Identity framework utilizes the [Stronghold project](https://github.com/iotaledger/stronghold.rs), a secure software implementation isolating digital secrets from exposure to hacks or leaks. Developers may choose to add other ways to manage the private keys in a different manner. - -## Privacy Considerations - -### Personal Identifiable Information - -The public IOTA Tangle networks are immutable networks. This means that once something is uploaded, it can never be completely removed. That directly conflicts with certain privacy laws such as GDPR, which have a 'right-to-be-forgotten' for Personal Identifiable Information (PII). As such, users should NEVER upload any PII to the Tangle, including inside DID Documents. The IOTA Identity framework allows Verifiable Credentials to be published to the Tangle directly, however this feature should only be utilized by Identity for Organisation and Identity for Things. - -### Correlation Risks - -As with any DID method, identities can be linked if they are used too often and their usage somehow becomes public. IOTA provides a simple solution for this problem: as creating identities is completely feeless, it is recommended to make new identities on a per interaction basis (Pairwise DIDs). The IOTA Identity framework will provide support for this in the future. diff --git a/docs/build/identity.rs/0.6/docs/specs/did/overview.mdx b/docs/build/identity.rs/0.6/docs/specs/did/overview.mdx deleted file mode 100644 index 91277d73bf7..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/did/overview.mdx +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: Overview -sidebar_label: Overview -description: IOTA Identity specifications overview. -image: /img/Identity_icon.png -keywords: - - specs - - specifications ---- - -TODO diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/CHANGELOG.md b/docs/build/identity.rs/0.6/docs/specs/didcomm/CHANGELOG.md deleted file mode 100644 index 64643b01921..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/CHANGELOG.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -title: Changelog -sidebar_label: Changelog ---- - - - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - -## [Unreleased] - -### Added - -### Changed - -### Removed - -## [0.1.0] - 2021-10-29 - -Initial version of IOTA DIDComm specification [(#379)](https://github.com/iotaledger/identity.rs/pull/379). - -### Added - -- Authentication protocol -- Connection protocol -- Issuance protocol -- Post protocol -- Presentation protocol -- Revocation Options protocol -- Revocation protocol -- Signing protocol] -- Termination protocol -- CredentialInfo resource -- Problem Reports resource diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/overview.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/overview.mdx deleted file mode 100644 index 405947cc500..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/overview.mdx +++ /dev/null @@ -1,83 +0,0 @@ ---- -title: IOTA DIDComm Specification -sidebar_label: Overview ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Introduction - -The IOTA DIDComm Specification standardizes how Self-Sovereign Identities (SSIs) can interact with each other and exchange information. Any applications that implement this standard will naturally be interoperable with each other. This reduces fragmentation in the ecosystem and therefore it is highly recommended to use this for any application built on top of the IOTA Identity framework. The specification defines several [protocols](#protocols), that can be used for common interactions like [issuing](./protocols/issuance.mdx) and [presenting](./protocols/presentation.mdx) verifiable credentials as well as supporting functions, such as [connection](./protocols/connection.mdx) establishment and [authentication](./protocols/authentication.mdx). Cross-cutting concerns like [error handling](./resources/problem-reports.mdx) and [credential negotiation](./resources/credential-info.mdx) are discussed in the [resources](#resources) section. - -The IOTA DIDComm Specification builds on the [DIDComm Messaging Specification](https://identity.foundation/didcomm-messaging/spec/) developed by the [Decentralized Identity Foundation (DIF)](https://identity.foundation/) and utilises [external protocols](#external-protocols) from the messaging specification for well-established interactions like feature discovery. - -This specification is meant to be a complete solution for common use cases and therefore contains protocols for common SSI interactions. It is possible to extend the specification with custom protocols and custom methods in existing protocols to support application-specific requirements. - -The specification itself is technology agnostic. Much like the [DIDComm Messaging Specification](https://identity.foundation/didcomm-messaging/spec/) there are no restrictions on transport layers and a concrete implementation can be done with many different technologies. - -## Conformance - -The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL -NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and -"OPTIONAL" in this specification are to be interpreted as described in - -[BCP 14](https://www.rfc-editor.org/info/bcp14)[(RFC 2119)]](https://www.rfc-editor.org/rfc/rfc2119.txt). - -## Versioning - -Protocols follow [Semantic Versioning 2.0](https://semver.org/) conventions. - -## Protocols - -The specification defines several [DIDComm protocols](https://identity.foundation/didcomm-messaging/spec/#protocols) that can be used for common SSI interactions: - -| Name | Version | Description | -| :------------------------------------------------------- | :-----: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Connection](./protocols/connection.mdx) | 0.1 | Establishes a [DIDComm connection](https://identity.foundation/didcomm-messaging/spec/#connections) between two parties. | -| [Authentication](./protocols/authentication.mdx) | 0.1 | Allows two parties to mutually authenticate, verifying the DID of each other. | -| [Presentation](./protocols/presentation.mdx) | 0.1 | Allows presentation of verifiable credentials that are issued to a holder and uniquely presented to a third-party verifier. | -| [Issuance](./protocols/issuance.mdx) | 0.1 | Allows the exchange of a verifiable credential between an issuer and a holder. | -| [Signing](./protocols/signing.mdx) | 0.1 | Allows a trusted-party to request the signing of an unsigned verifiable credential by an issuer. | -| [Revocation](./protocols/revocation.mdx) | 0.1 | Allows to request revocation of an issued credential, either by the holder or a trusted-party. | -| [Revocation Options](./protocols/revocation-options.mdx) | 0.1 | Allows discovery of available [`RevocationInfo`](./protocols/revocation.mdx#RevocationInfo) types for use with the [revocation](./protocols/revocation.mdx) protocol. | -| [Post](./protocols/post.mdx) | 0.1 | Allows the sending of a single message with arbitrary data. | -| [Termination](./protocols/termination.mdx) | 0.1 | Indicates the graceful termination of a connection. | - -## External Protocols - -In addition to the protocols defined in this specification, we RECOMMEND implementors use the following well-known protocols: - -| Name | Version | Description | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-----: | :------------------------------------------------------------------------------------------------------ | -| [Discover Features](https://github.com/decentralized-identity/didcomm-messaging/blob/ef997c9d3cd1cd24eb182ffa2930a095d3b856a9/docs/spec-files/feature_discovery.mdx) | 2.0 | Describes how agents can query one another to discover which features they support, and to what extent. | -| [Trust Ping](https://github.com/decentralized-identity/didcomm-messaging/blob/9039564e143380a0085a788b6dfd20e63873b9ca/docs/spec-files/trustping.mdx) | 1.0 | A standard way for agents to test connectivity, responsiveness, and security of a DIDComm channel. | - -## Resources - -Additionally, general guidelines on concerns across protocols are provided: - -| Name | Description | -| :------------------------------------------------- | :--------------------------------------------------------------------------- | -| [Problem Reports](./resources/problem-reports.mdx) | Definitions of expected problem reports and guidance on global handling. | -| [Credential Info](./resources/credential-info.mdx) | Definition of methods to negotiate a specific kind of verifiable credential. | - -## Diagrams - -The diagrams in this specification follow the [BPMN 2.0](https://www.omg.org/spec/BPMN/2.0/) notation. The diagrams are created with https://www.diagrams.net, the source is embedded in the `.svg` files. - -## Changelog - -See [CHANGELOG](./CHANGELOG.md). - -## Future Work - -◈ If necessary, discuss ways for some agent to request the start of an interaction. This has narrow use cases, but might be interesting in the long run. -◈ Add section or article on anonymous encryption, sender authenticated encryption, signed messages. Include a table of comparisons with guarantees? E.g. authentication, eavesdropping protection, _integrity_ etc. diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/authentication.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/authentication.mdx deleted file mode 100644 index e38f7360a96..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/authentication.mdx +++ /dev/null @@ -1,219 +0,0 @@ ---- -title: Authentication -sidebar_label: Authentication ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -This protocol allows two parties to mutually authenticate by disclosing and verifying the [DID] of each other. On successful completion of this protocol, it is expected that [sender authenticated encryption][sae] may be used between the parties for continuous authentication. - -### Relationships - -- [Connection](./connection.mdx): it is RECOMMENDED to establish [anonymous encryption](https://identity.foundation/didcomm-messaging/spec/#anonymous-encryption) on [connection](./connection.mdx) to prevent revealing the DID of either party to eavesdroppers. - -### Example Use-Cases - -- A connected sensor wants to make sure only valid well-known parties connect to it, before allowing access. -- A customer wants to make sure they are actually connecting to their bank, before presenting information. -- An organisation wants to verify the DID of the employer before issuing access credentials. - -### Roles - -- Requester: initiates the authentication. -- Responder: responds to the authentication request. - -### Interaction - -![AuthenticationDiagram](/img/didcomm/authentication.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. authentication-request {#authentication-request} - -- Type: `iota/authentication/0.1/authentication-request` -- Role: [requester](#roles) - -Sent to initiate the authentication process. This MUST be a [signed DIDComm message][sdm] to provide some level of trust to the [responder](#roles). However, even when signed it is possible to replay an [authentication-request](#authentication-request), so this message alone is insufficient to prove the DID of the [requester](#roles). In addition to a unique `requesterChallenge`, the `created_time` and `expires_time` [DIDComm message headers](https://identity.foundation/didcomm-messaging/spec/#message-headers) SHOULD be used to mitigate such replay attacks. Note that even a successful replay would only reveal the DID of the responder, authentication of a malicious requester will still fail without access to the original requester's private keys due to the use of challenges. - -#### Structure - -```json -{ - "did": DID, // REQUIRED - "requesterChallenge": string, // REQUIRED - "upgradeEncryption": string, // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| [`did`][did] | [DID] of the [requester](#roles).[^1] | ✔ | -| `requesterChallenge` | A random string unique per [authentication-request](#authentication-request) by a [requester](#roles) to help mitigate replay attacks. | ✔ | -| `upgradeEncryption` | A string indicating whether [sender authenticated encryption][sae] should be used in the following messages. One of `["required", "optional", "unsupported"]`.[^2] | ✔ | - -[^1] The signing key used for the [signed DIDComm envelope][sdm] wrapping this message MUST be an [authentication method][auth_method] in the DID document corresponding to `did`, as per the [DIDComm specification][didcomm_keys]. - -[^2] The `upgradeEncryption` field allows negotiation of whether or not to use [sender authenticated encryption][sae] for the [authentication](#authentication) protocol and for all messages that follow it. It is RECOMMENDED to specify `"required"` as it offers various guarantees of continuous authentication and payload _integrity_ for every message. The available options are: - -- `"required"`: the [responder](#roles) MUST initiate [sender authenticated encryption][sae], from the following [authentication-response](#authentication-response) message onwards, or send a problem-report. -- `"optional"`: the [responder](#roles) chooses whether or not to use [sender authenticated encryption][sae]. -- `"unsupported"`: the [responder](#roles) MUST NOT use [sender authenticated encryption][sae]. A [responder](#roles) MAY reject [authentication-requests](#authentication-request) that do not support encryption. - Any other value for `upgradeEncryption` is invalid and should result in an invalid-request problem-report. - -#### Examples - -1. Request payload requiring encryption: - -```json -{ - "did": "did:iota:9rK6DPF46MCEzgfLD8AHFsaTuMqvmRo6kbXfjqQJPJmC", - "requesterChallenge": "81285532-b72a-4a99-a9bd-b470475bc24f", - "upgradeEncryption": "required" -} -``` - -### 2. authentication-response {#authentication-response} - -- Type: `iota/authentication/0.1/authentication-response` -- Role: [responder](#roles) - -Sent in response to an [authentication-request](#authentication-request), proving the DID of the [responder](#roles). Optionally establishes [sender authenticated encryption][sae] based on the value of `upgradeEncryption` in the preceding [authentication-request](#authentication-request). If `upgradeEncryption` was `"required"` and this message is not encrypted, or `"unsupported"` and this message is encrypted, the [requester](#roles) MUST issue a problem-report and abort the authentication. - -This message MUST be a [signed DIDComm message][sdm], even if [sender authenticated encryption][sae] is used. This is to ensure an [authentication key][auth_method] is used to sign the challenge, in accordance with the [DID specification][auth_method], and because there may be increased security controls or guarantees compared to the [keyAgreement](https://www.w3.org/TR/did-core/#key-agreement) keys used for [sender authenticated encryption][sae]. - -#### Structure - -```json -{ - "did": DID, // REQUIRED - "requesterChallenge": string, // REQUIRED - "responderChallenge": string, // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| [`did`][did] | [DID] of the [responder](#roles).[^1] | ✔ | -| `requesterChallenge` | Must match the `requesterChallenge` in the preceding [authentication-request](#authentication-request). | ✔ | -| `responderChallenge` | A random string unique per [authentication-response](#authentication-response) by a [responder](#roles) to help mitigate replay attacks. | ✔ | - -[^1] The signing key used for the [signed DIDComm envelope][sdm] wrapping this message MUST be an [authentication method][auth_method] in the DID document corresponding to the `did`, as per the [DIDComm specification][didcomm_keys]. - -#### Examples - -1. Responder presenting their [DID] and offering a challenge to the requester: - -```json -{ - "did": "did:iota:8cU6DPF56MDEugfLF8AHFaaTuMQvmRo6kbxfjqQJpJmC", - "requesterChallenge": "81285532-b72a-4a99-a9bd-b470475bc24f", - "responderChallenge": "b1f0dc02-85a3-4438-8786-b625f11f1be4" -} -``` - -### 3. authentication-result {#authentication-result} - -- Type: `iota/authentication/0.1/authentication-result` -- Role: [requester](#roles) - -This message finalises the mutual authentication, proving control over the DID of the [requester](#roles) to the [responder](#roles). Similar to [authentication-response](#authentication-response), this message MUST be a [signed DIDComm message][sdm]. - -This MUST or MUST NOT use [sender authenticated encryption][sae] depending on the outcome of the `upgradeEncryption` negotiation in the preceding [authentication-response](#authentication-response) message, otherwise resulting in a problem-report and failure of the authentication protocol. For example, if `upgradeEncryption` was `optional` and the [authentication-response](#authentication-response) used [sender authenticated encryption][sae], then the [authentication-result](#authentication-result) MUST be encrypted to be valid. - -#### Structure - -```json -{ - "responderChallenge": string // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------- | :--------------------------------------------------------------------------------------------------- | :------- | -| `responderChallenge` | Must match the `challenge` in the preceding [authentication-response](#authentication-response).[^1] | ✔ | - -[^1] The signing key used for the [signed DIDComm envelope][sdm] wrapping this message MUST be an [authentication method][auth_method] in the DID document corresponding to the `did` of the [requester](#roles) in the [authentication-request](#authentication-request), as per the [DIDComm specification][didcomm_keys]. - -#### Examples - -1. Requester responding with the responder's challenge from the previous message: - -```json -{ - "responderChallenge": "0768e82d-f498-4f38-8686-918325f9560d" -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------ | -| `e.p.msg.iota.authentication.reject-authentication` | [authentication-request](#authentication-request), [authentication-response](#authentication-response), [authentication-result](#authentication-result) | The party rejects an authentication request/response/result for any reason. | -| `e.p.msg.iota.authentication.reject-authentication.missing-keys` | [authentication-request](#authentication-request), [authentication-response](#authentication-response), [authentication-result](#authentication-result) | The party rejects an authentication request/response due to the other party lacking a supported `keyAgreement` section in the DID document. | -| `e.p.msg.iota.authentication.reject-authentication.untrusted-identity` | [authentication-request](#authentication-request), [authentication-response](#authentication-response) | The party rejects an authentication request/response due to the claimed DID of the other party. | -| `e.p.msg.iota.authentication.reject-authentication.encyption-required` | [authentication-request](#authentication-request), [authentication-response](#authentication-response), [authentication-result](#authentication-result) | The party rejects an authentication request/response/result due to the lack of [sender authenticated encryption][sae]. | -| `e.p.msg.iota.authentication.reject-authentication.encyption-unsupported` | [authentication-request](#authentication-request), [authentication-response](#authentication-response), [authentication-result](#authentication-result) | The party rejects an authentication request/response/result because it does not support [sender authenticated encryption][sae]. | - -## Considerations - -This section is non-normative. - -- **Trust**: this [authentication](#authentication) protocol only verifies that both parties have access to the necessary private keys (which could become compromised) associated with their DID documents. Verifying whether a DID document is [bound to a physical identity](https://www.w3.org/TR/did-core/#binding-to-physical-identity) may require additional interactions. Verifying whether a DID can be trusted can be achieved by, for instance: - - requesting a verifiable presentation of credentials issued by a trusted third party, such as a government, - - using the [Well Known DID Configuration](https://identity.foundation/.well-known/resources/did-configuration/) or embedding the DID in a DNS record to tie an identity to a website or domain, - - using an allowlist of trusted DIDs, - - exchanging DIDs out-of-band in a secure manner (note that some [connection](./connection.mdx) invitations could be altered by malicious parties depending on the medium). -- **Authorisation**: the permissions and capabilities of either party may still need to be established after [authentication](#authentication), either by [verifiable presentation](./presentation.mdx) as mentioned above or other methods such as JWT tokens -- **Privacy**: the [responder](#roles) may be subject to probing whereby their DID may be revealed even with the use of [sender authenticated encryption][sae], as the `skid` message header is linked to their DID. This is possible if the [responder](#roles) chooses to accept the [authentication-request](#authentication-request) of an unknown [requester](#roles), or the [requester](#roles) successfully replays an [authentication-request](#authentication-request) from a DID the [requester](#roles) trusts. - -## Unresolved Questions - -- Enforce signed DIDComm messages on top of sender-authenticated encryption or keep them optional? Usually unnecessary and DIDComm recommends against this since it's redundant and due to non-repudiation may decrease security and privacy by allowing participants to prove to third parties that authentication occurred. - - - https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message - - https://github.com/hyperledger/aries-rfcs/blob/master/concepts/0049-repudiation/README.md#summary - -- How to protect the DID of the responder (`skid` field in sender-authenticated message) to prevent probing identities even with anonymous encryption? - - - https://github.com/decentralized-identity/didcomm-messaging/issues/197 - - https://github.com/decentralized-identity/didcomm-messaging/issues/219 - -- Add examples of full signed and sender-authenticated messages with headers for better illustration? - -## Related Work - -- Aries Hyperledger: - - DID Exchange protocol: https://github.com/hyperledger/aries-rfcs/tree/main/features/0023-did-exchange - - DIDAuthZ: https://github.com/hyperledger/aries-rfcs/tree/main/features/0309-didauthz -- Jolocom: https://jolocom.github.io/jolocom-sdk/1.0.0/guides/interaction_flows/#authentication - - - -[did]: https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers -[auth_method]: https://www.w3.org/TR/did-core/#authentication -[didcomm_keys]: https://identity.foundation/didcomm-messaging/spec/#did-document-keys -[sae]: https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption -[sdm]: https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/connection.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/connection.mdx deleted file mode 100644 index 11fc3499189..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/connection.mdx +++ /dev/null @@ -1,256 +0,0 @@ ---- -title: Connection -sidebar_label: Connection ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -Allows establishment of a [DIDComm connection](https://identity.foundation/didcomm-messaging/spec/#connections) between two parties. The connection may be established by an explicit invitation delivered [out-of-band][out_of_band]—such as a QR code, URL, or email—or by following an implicit invitation in the form of a [service endpoint][didcomm_service_endpoint] attached to a public DID document. - -### Relationships - -- [Termination](./termination.mdx): the DIDComm connection may be gracefully concluded using the [termination protocol](./termination.mdx). -- [Authentication](./authentication.mdx): the authentication protocol can be used to authenticate parties participating in the established [connection](./connection.mdx). -- [Feature Discovery](https://github.com/decentralized-identity/didcomm-messaging/blob/ef997c9d3cd1cd24eb182ffa2930a095d3b856a9/docs/spec-files/feature_discovery.mdx): feature discovery can be used to learn about the capabilities of the other party after connection. - -### Example Use-Cases - -- A corporation offers a QR code on their website for customers to connect to their services. -- A person sends an invitation as an email to a friend, to exchange information. -- A device has a service embedded in their DID, that allows others to connect to it, in order to read data. - -### Roles - -- Inviter: offers methods to establish connections. -- Invitee: may connect to the inviter using offered methods. - -### Interaction - -![ConnectionDiagram](/img/didcomm/connection.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. invitation {#invitation} - -- Type: `https://didcomm.org/out-of-band/2.0/invitation` -- Role: [inviter](#roles) - -A message containing information on how to connect to the inviter. This message is delivered out-of-band, e.g. in form of a link or QR code. The message contains all information required to establish a DIDComm connection. - -#### Structure - -The general structure of the invitation message is described in the [Out Of Band Messages of the DIDComm specification][out_of_band]. Note that the invitation message may be [signed](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message) to provide [tamper resistance](https://identity.foundation/didcomm-messaging/spec/#tamper-resistant-oob-messages). - -The actual invitation is contained in the `attachments` field in the message, which is structured as follows: - -```json -{ - "serviceId": DIDUrl, // OPTIONAL - "service": { - "serviceEndpoint": string, // REQUIRED - "accept": [string], // OPTIONAL - "recipientKeys": [DIDUrl | DIDKey], // OPTIONAL - "routingKeys": [DIDUrl | DIDKey], // OPTIONAL - }, // OPTIONAL -``` - -| Field | Description | Required | -| :----------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `serviceId` | A string representing a [DIDUrl][didurl] referencing a resolvable [service][service].[^1] [^2] | ✖ | -| [`service`][service] | A structure analogous to the [DID service specification][service], including all information necessary to establish a connection with the [inviter](#roles).[^1] | ✖ | -| [`serviceEndpoint`](https://www.w3.org/TR/did-core/#dfn-serviceendpoint) | A [URI](https://www.rfc-editor.org/rfc/rfc3986) including all details needed to connect to the [inviter](#roles). | ✔ | -| [`accept`][didcomm_service_endpoint] | An optional array of [DIDComm profiles](https://identity.foundation/didcomm-messaging/spec/#defined-profiles) in the order of preference for sending a message to the endpoint. If omitted, defer to the `accept` field of the invitation body. | ✖ | -| `recipientKeys` | An ordered array of [DIDUrls][didurl] or [`did:key`][did_key] strings referencing public keys, any of which may be used for [anonymous encryption][anoncrypt].[^3] [^4] | ✖ | -| [`routingKeys`][didcomm_service_endpoint] | An ordered array of [DIDUrls][didurl] or [`did:key`][did_key] strings referencing keys to be used when preparing the message for transmission; see [DIDComm Routing](https://identity.foundation/didcomm-messaging/spec/#routing).[^4] | ✖ | - -[^1] One of `serviceId` or `service` MUST be present for the [invitee](#roles) to be able to connect. If both fields are present, the [invitee](#roles) SHOULD default to the `serviceId`. - -[^2] It is RECOMMENDED that the service referenced by `serviceId` conforms to the ["DIDCommMessaging" service type from the DIDComm specification][didcomm_service_endpoint] as it allows `routingKeys` to be included if necessary. The DID document referenced by `serviceId` SHOULD include one or more [`keyAgreement`](https://www.w3.org/TR/did-core/#key-agreement) sections to use for [anonymous encryption][anoncrypt]; the absence of any [`keyAgreement`](https://www.w3.org/TR/did-core/#key-agreement) section implies no [anonymous encryption][anoncrypt] will be used for the connection and an [invitee](#roles) may choose to reject such an invitation. A public `serviceId` may reveal the identity of the [inviter](#roles) to anyone able to view the invitation; if privacy is a concern using an inline `service` should be preferred. For a public organisation whose DID is already public knowledge, using `serviceId` has a few benefits: it establishes some level of trust that the [invitee](#roles) may be connecting to the correct party since a service from their public DID document is used, and the invitation may be re-used indefinitely even if the service referenced is updated with different endpoints. When using `service` instead of `serviceId`, a signed invitation may provide a similar level of trust. However, neither should be used as a complete replacement for interactive authentication due to the risk of man-in-the-middle attacks. - -[^3] Note that `recipientKeys` may have multiple entries in order of preference of the [inviter](#roles); this is to offer multiple key types (e.g. Ed25519, X25519) and an [invitee](#roles) may choose any key with which they are compatible. These keys may be static or generated once per invitation. Omitting `recipientKeys` implies that [anonymous encryption][anoncrypt] will not be used in the ensuing DIDComm connection. It is RECOMMENDED to include as [anonymous encryption][anoncrypt] ensures message integrity and protects communications from eavesdroppers over insecure channels. [Invitees](#roles) may choose to reject invitations that do not include `recipientKeys` if they want to enforce [anonymous encryption][anoncrypt]. - -[^4] Implementors should avoid using a `DIDUrl` for the `recipientKeys` or `routingKeys` if privacy is a concern, as may reveal the identity of the [inviter](#roles) to any party other than the [invitee](#roles) that intercepts the invitation. However, using a `DIDUrl` may be useful as it allows for key-rotation without needing to update the invitation. - -#### Examples - -The following examples include the entire DIDComm message structure for illustration, including [message headers](https://identity.foundation/didcomm-messaging/spec/#message-headers) with the actual [invitation payload](#invitation) defined in this specification included in the [attachments](https://identity.foundation/didcomm-messaging/spec/#attachments) section. - -For further information on how to encode the invitation message for delivery refer to the [DIDComm specification](https://identity.foundation/didcomm-messaging/spec/#standard-message-encoding). - -1. Invitation with a single attachment: - -```json -{ - "typ": "application/didcomm-plain+json", - "type": "https://didcomm.org/out-of-band/2.0/invitation", - "id": "fde5eb9e-0560-48cf-b860-acd178c1e0b0", - "body": { - "accept": ["didcomm/v2"] - }, - "attachments": [ - { - "@id": "request-0", - "mime-type": "application/json", - "data": { - "json": { - "service": { - "serviceEndpoint": "wss://example.com/path", - "recipientKeys": [ - "did:key:z6LSoMdmJz2Djah2P4L9taDmtqeJ6wwd2HhKZvNToBmvaczQ" - ], - "routingKeys": [] - } - } - } - } - ] -} -``` - -Refer to the [DIDComm specification](https://identity.foundation/didcomm-messaging/spec/#standard-message-encoding) for further information on how to encode the invitation message for delivery. - -2. Invitation with a goal indicated and two attachments in order of preference. An [invitee](#roles) should pick the first one with which they are compatible: - -```json -{ - "typ": "application/didcomm-plain+json", - "type": "https://didcomm.org/out-of-band/2.0/invitation", - "id": "fde5eb9e-0560-48cf-b860-acd178c1e0b0", - "body": { - "goal_code": "issue-vc", - "goal": "To issue a Faber College Graduate credential", - "accept": ["didcomm/v2"] - }, - "attachments": [ - { - "@id": "request-0", - "mime-type": "application/json", - "data": { - "json": { - "service": { - "serviceEndpoint": "wss://example.com/path", - "accept": ["didcomm/v2"], - "recipientKeys": [ - "did:key:z6LSoMdmJz2Djah2P4L9taDmtqeJ6wwd2HhKZvNToBmvaczQ", - "did:key:z82Lm1MpAkeJcix9K8TMiLd5NMAhnwkjjCBeWHXyu3U4oT2MVJJKXkcVBgjGhnLBn2Kaau9" - ], - "routingKeys": [ - "did:key:z6LStiZsmxiK4odS4Sb6JmdRFuJ6e1SYP157gtiCyJKfrYha" - ] - } - } - } - }, - { - "@id": "request-1", - "mime-type": "application/json", - "data": { - "json": { - "serviceId": "did:iota:123456789abcdefghi#didcomm-1" - } - } - } - ] -} -``` - -### 2. connection {#connection} - -- Type: `iota/connection/0.1/connection` -- Role: [invitee](#roles) - -Following a successful connection, the [invitee](#roles) sends its public keys necessary to establish [anonymous encryption][anoncrypt]. This may be preceded by an [invitation](#invitation) message, or the [invitee](#roles) may connect directly to the [inviter](#roles) in the case of an implicit invitation. - -#### Structure - -```json -{ - "recipientKey": DIDUrl | DIDKey, // OPTIONAL - "routingKeys": [DIDUrl | DIDKey], // OPTIONAL -} -``` - -| Field | Description | Required | -| :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `recipientKey` | A [DIDUrl][didurl] or [`did:key`][did_key] strings referencing a public key of the [invitee](#roles) to be used for [anonymous encryption][anoncrypt].[^1] [^2] | ✖ | -| [`routingKeys`][didcomm_service_endpoint] | An ordered array of [DIDUrls][didurl] or [`did:key`][did_key] strings referencing keys to be used by the [inviter](#roles) when preparing the message for transmission; see [DIDComm Routing](https://identity.foundation/didcomm-messaging/spec/#routing).[^2] | ✖ | - -The `id` of the preceding [invitation](#invitation) message MUST be used as the `pthid` header property on this message. Both the `thid` and `pthid` properties MUST be omitted in the case of an implicit invitation when connecting to a public service endpoint of an [inviter](#roles). See [DIDComm Message Headers](https://identity.foundation/didcomm-messaging/spec/#message-headers) for more information. - -[^1] If present, the `recipientKey` sent by the [`invitee`](#roles) MUST match the key type (e.g. Ed25519, X25519) of one of the `recipientKeys` in the [invitation](#invitation) message, or of a `keyAgreement` public key attached to the [inviter's](#roles) DID document in the case of an implicit invitation. The `recipientKey` should be omitted if no `recipientKeys` or `keyAgreement` sections are present, or if the [invitee](#roles) does not wish to use [anonymous encryption][anoncrypt] for the connection. An [inviter](#roles) may choose to reject connection messages that omit a `recipientKey`, terminating the connection. - -[^2] Similar to the considerations for the [invitation](#invitation) message, implementors should avoid using a `DIDUrl` for the `recipientKey` or `routingKeys` as it may reveal the identity of the [invitee](#roles) to eavesdroppers prior to encryption being established. Using a `DIDUrl` for key rotation is less of a concern for a [connection](#connection) message as, unlike an [invitation](#invitation), the message is intended to be transient and should not persist beyond a single connection attempt. - -#### Examples - -1. Connection with a P-384 Key DID as the recipient key: - -```json -{ - "recipientKey": "did:key:z82LkvCwHNreneWpsgPEbV3gu1C6NFJEBg4srfJ5gdxEsMGRJUz2sG9FE42shbn2xkZJh54" -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their custom application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :------------------------------------------ | :------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------- | -| `e.p.msg.iota.connection.reject-connection` | [connection](#connection) | [Inviter](#roles) rejects a connection request for any reason, e.g. untrusted [invitee](#roles) or lacking `recipientKey` for anonymous encryption. | - -## Considerations - -This section is non-normative. - -- **Authentication**: implementors SHOULD NOT use any information transmitted in the connection protocol for direct authentication or proof of identity. See the [authentication](./authentication.mdx) protocol. - -## Unresolved Questions - -- List supported handshake protocols for authentication post-connection? -- How do parties know what to do post-connection, send protocol in the invitation, or does one party just try to start a protocol immediately? For custom/corporate applications likely hard-coded, for general SSI wallets, it is an open question. - -## Related Work - -- Aries Hyperledger: - - Connection protocol: https://github.com/hyperledger/aries-rfcs/tree/main/features/0160-connection-protocol - - Out-of-Band protocol: https://github.com/hyperledger/aries-rfcs/tree/main/features/0434-outofband - - DID Exchange protocol: https://github.com/hyperledger/aries-rfcs/tree/main/features/0023-did-exchange - -## Further Reading - -- [DIDComm Connections](https://identity.foundation/didcomm-messaging/spec/#connections) -- [DIDComm Out Of Band Messages][out_of_band] -- [DIDComm Service Endpoint][didcomm_service_endpoint] -- [DID Services][service] -- [Aries Hyperledger Goal Codes](https://github.com/hyperledger/aries-rfcs/tree/main/concepts/0519-goal-codes) - - - -[anoncrypt]: https://identity.foundation/didcomm-messaging/spec/#anonymous-encryption -[didurl]: https://www.w3.org/TR/did-core/#did-url-syntax -[did_key]: https://w3c-ccg.github.io/did-method-key/ -[service]: https://www.w3.org/TR/did-core/#services -[out_of_band]: https://github.com/decentralized-identity/didcomm-messaging/blob/49935b7b119591a009ce61d044ba9ad6fa40c7b7/docs/spec-files/out_of_band.md -[didcomm_service_endpoint]: https://identity.foundation/didcomm-messaging/spec/#did-document-service-endpoint diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/issuance.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/issuance.mdx deleted file mode 100644 index 83cd9d4823c..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/issuance.mdx +++ /dev/null @@ -1,448 +0,0 @@ ---- -title: Issuance -sidebar_label: Issuance ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -Allows a [holder](#roles) to request a [verifiable credential][vc] from an [issuer](#roles). The [issuer](#roles) may alternatively initiate the issuance without a request from the [holder](#roles). This protocol also allows the [issuer](#roles) to request additional information and to offload the actual signing to a different party. - -### Relationships - -- [Presentation](./presentation.mdx): the [issuer](#roles) may request a [verifiable presentation](https://www.w3.org/TR/vc-data-model/#presentations-0) from the [holder](#roles) during the course of this protocol if additional information is required. -- [Signing](./signing.mdx): the [issuer](#roles) may delegate signing to another [issuer](#roles) if they lack the needed authority or private key, in which case the [issuer](#roles) takes on the role of [trusted-party](./signing.mdx#roles). - -### Example Use-Cases - -- A university issues a degree to a graduate that can be verified by potential employers. -- A resident requests proof of address from their city council. -- An insurer issues proof that a company has liability insurance. - -### Roles - -- [Holder](https://www.w3.org/TR/vc-data-model/#dfn-holders): stores one or more verifiable credentials. A holder is usually but not always the [subject][subject] of those credentials. -- [Issuer](https://www.w3.org/TR/vc-data-model/#dfn-issuers): creates verifiable credentials asserting claims about one or more [subjects][subject], transmitted to a holder. - -### Interaction - -![IssuanceDiagram](/img/didcomm/issuance.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. issuance-request {#issuance-request} - -- Type: `iota/issuance/0.1/issuance-request` -- Role: [holder](#roles) - -The [holder](#roles) requests a single verifiable credential from the [issuer](#roles) of a particular kind. - -#### Structure - -```json -{ - "subject": DID, // REQUIRED - "credentialInfo": CredentialInfo, // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| [`subject`][subject] | [DID](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers) of the [credential subject][subject][^1]. | ✔ | -| `credentialInfo` | A [CredentialInfo](../resources/credential-info.mdx) object, specifying a credential kind requested by the [holder](#roles).[^2] [^3] [^4] | ✔ | - -[^1] The [holder](#roles) is usually but not always the [subject][subject] of the requested credential. There may be custodial, legal guardianship, or delegation situations where a third-party requests, or is issued a credential on behalf of a subject. It is the responsibility of the [issuer](#roles) to ensure authorization in such cases. - -[^2] The `credentialInfo` could be hard-coded, communicated in-band, discovered out-of-band, or be pre-sent by an [issuer](#roles). The [issuer](#roles) SHOULD reject the request with a `problem-report` if it does not support the requested `credentialInfo`. - -[^3] With [CredentialType2021], the `type` MAY be under-specified if the exact type is unknown or if the resulting type depends on the identity or information of the subject or holder. E.g. the `type` could be as general as `["VerifiableCredential"]` if the issuer issues only a singular type of credential or decides the credential based on other information related to the subject. - -[^4] With [CredentialType2021], the [holder](#roles) MAY specify one or more trusted issuers they would like to sign the resulting credential. The [issuer](#roles) SHOULD reject the request with a `problem-report` if it supports none of the requested `issuer` entries. However, there are circumstances where an `issuer` is no longer supported or was compromised, so this behavior should be decided based on the application. - -An [issuer](#roles) wanting to preserve privacy regarding which exact credential kinds, types, or issuers they support should be careful with the information they disclose in `problem-reports` when rejecting requests. E.g. a `problem-report` with only a `reject-request` descriptor discloses less information than the `reject-request.invalid-type` or `reject-request.invalid-trusted-issuer` descriptors, as the latter two could be used to determine supported types or signing issuers by process of elimination. - -#### Examples - -1. Request any drivers licence credential using [CredentialType2021]: - -```json -{ - "subject": "did:example:c6ef1fe11eb22cb711e6e227fbc", - "credentialInfo": { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "DriversLicence"] - } -} -``` - -2. Request a university degree credential from either supported trusted issuer using [CredentialType2021]: - -```json -{ - "subject": "did:example:c6ef1fe11eb22cb711e6e227fbc", - "credentialInfo": { - "credentialInfoType": "CredentialType2021", - "type": [ - "VerifiableCredential", - "UniversityDegreeCredential", - "BachelorOfArtsDegreeCredential" - ], - "issuer": [ - "did:example:76e12ec712ebc6f1c221ebfeb1f", - "did:example:f1befbe122c1f6cbe217ce21e67" - ] - } -} -``` - -### 2. issuance-offer {#issuance-offer} - -- Type: `iota/issuance/0.1/issuance-offer` -- Role: [issuer](#roles) - -The [issuer](#roles) offers a single, unsigned credential to the [holder](#roles), matching the preceding [`issuance-request`](#issuance-request) if present. The [issuer](#roles) may set an expiry date for the offer and require non-repudiable proof by the [holder](#roles) that the offer was received. - -#### Structure - -```json -{ - "unsignedCredential": Credential, // REQUIRED - "offerChallenge": { - "challenge": string, // REQUIRED - "credentialHash": string, // REQUIRED - }, // OPTIONAL - "offerExpiry": DateTime // OPTIONAL -} -``` - -| Field | Description | Required | -| :------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| [`unsignedCredential`][vc] | Unsigned [credential][vc] being offered to the [holder](#roles). This MUST NOT include a `proof` section. | ✔ | -| `offerChallenge` | If present, indicates the [issuer](#issuer) requires the acceptance of the credential to be signed by the [holder](#holder) in the following [issuance-response](#issuance-response) for non-repudiation.[^1] | ✖ | -| `challenge` | A random string that should be unique per [issuance-offer](#issuance-offer). | ✔ | -| `credentialHash` | The [Base58](https://tools.ietf.org/id/draft-msporny-base58-01.html)-encoded [SHA-256 digest](https://www.rfc-editor.org/rfc/rfc4634) of the `unsignedCredential` formatted according to the [JSON Canonicalization Scheme](https://tools.ietf.org/id/draft-rundgren-json-canonicalization-scheme-00.html). | ✔ | -| `offerExpiry` | A string formatted as an [XML DateTime](https://www.w3.org/TR/xmlschema11-2/#dateTime) normalized to UTC 00:00:00 and without sub-second decimal precision. E.g: `"2021-12-30T19:17:47Z"`.[^2] | ✖ | - -[^1] Issuing challenges should be done with due consideration to security and privacy concerns: not all applications require non-repudiation to third-parties and a [holder](#roles) [may wish to deny that they ever requested or accepted a particular credential](https://github.com/hyperledger/aries-rfcs/blob/main/concepts/0049-repudiation/README.md#summary). The challenge SHOULD NOT be used for authentication of the [holder](#roles); see the [authentication](./authentication.mdx) protocol and [sender authenticated encryption](https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption). - -[^2] If present, an `offerExpiry` indicates that the [issuer](#roles) MAY rescind the offer and abandon the protocol if an affirmative [issuance-response](#issuance-response) is not received before the specified datetime. Note that the `offerExpiry` should override any default message timeouts. - -#### Examples - -1. Offer a degree credential: - -```json -{ - "unsignedCredential": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f", - "issuanceDate": "2021-05-03T19:73:24Z", - "credentialSubject": { - "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", - "degree": { - "type": "BachelorDegree", - "name": "Bachelor of Science and Arts" - } - } - } -} -``` - -2. A time-limited offer for a degree credential with a signature requested: - -```json -{ - "unsignedCredential": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f", - "issuanceDate": "2021-01-05T19:37:24Z", - "credentialSubject": { - "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", - "degree": { - "type": "BachelorDegree", - "name": "Bachelor of Science and Arts" - } - } - }, - "offerChallenge": { - "challenge": "d7b7869e-fec3-4de9-84bb-c3a43bacff33", - "credentialHash": "28Ae7AdqzyMyF9pmnwUNK1Q7VT3EzDDGEj1Huk7uYQT94KYAhQzEPyhoF5Ugs3totUugLPpghGmE9HaG8usJZcZv" - }, - "offerExpiry": "2021-01-05T20:07:24Z" -} -``` - -### 3. issuance-response {#issuance-response} - -- Type: `iota/issuance/0.1/issuance-response` -- Role: [holder](#roles) - -The [holder](#roles) responds to a [`issuance-offer`](#issuance-offer) by accepting or disputing the offer and optionally signing the response for non-repudiation. - -#### Structure - -```json -{ - "accepted": bool, // REQUIRED - "disputes": [Dispute], // OPTIONAL - "signature": { - "offerChallenge": { - "challenge": string, // REQUIRED - "credentialHash": string, // REQUIRED - }, // REQUIRED - "proof": Proof, // REQUIRED - } // OPTIONAL -} -``` - -| Field | Description | Required | -| :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `accepted` | Indicates if the [holder](#roles) accepts the offered credential from [`issuance-offer`](#issuance-offer). MUST be `false` if any `disputes` are present. | ✔ | -| [`disputes`](https://www.w3.org/TR/vc-data-model/#disputes) | Allows the [holder](#roles) to [`dispute`](https://www.w3.org/TR/vc-data-model/#disputes) one or more claims in the credential. | ✖ | -| `signature` | This SHOULD be present if a `offerChallenge` was included in the preceding [`issuance-offer`](#issuance-offer).[^1] | ✖ | -| `offerChallenge` | This MUST match the `offerChallenge` in the preceding [`issuance-offer`](#issuance-offer). | ✔ | -| [`proof`](https://w3c-ccg.github.io/ld-proofs/) | Signature of the [holder](#roles) on the `offerChallenge`. | ✔ | - -[^1] A valid `signature` allows the [issuer](#roles) to prove that the credential was accepted by the [holder](#roles). If present, the [issuer](#roles) MUST validate the `proof` is correct and signed with an unrevoked [verification method](https://www.w3.org/TR/did-core/#dfn-verification-method), and issue a problem-report if not. The [issuer](#roles) SHOULD terminate the protocol if no `signature` is present and a `offerChallenge` was included in the preceding [issuance-offer](#issuance-offer) message. An explicit `signature` is used instead of a [signed DIDComm message](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message) to avoid the need to store the entire credential for auditing purposes; the hash is sufficient to prove a particular credential was accepted. - -#### Examples - -1. Accept a credential offer: - -```json -{ - "accepted": true, - "disputes": [] -} -``` - -2. Accept a credential offer including a signature: - -```json -{ - "accepted": true, - "disputes": [], - "signature": { - "offerChallenge": { - "challenge": "d7b7869e-fec3-4de9-84bb-c3a43bacff33", - "credentialHash": "28Ae7AdqzyMyF9pmnwUNK1Q7VT3EzDDGEj1Huk7uYQT94KYAhQzEPyhoF5Ugs3totUugLPpghGmE9HaG8usJZcZv", - }, - "proof": {...} - } -} -``` - -3. Reject a credential offer with disputes: - -```json -{ - "accepted": false, - "disputes": [{ - "@context": [ - "https://www.w3.org/2018/credentials/v1", - ], - "id": "6e8e989e-749e-4ed8-885b-b2a2bb64835f", - "type": ["VerifiableCredential", "DisputeCredential"], - "credentialSubject": { - "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a", - "currentStatus": "Disputed", - "statusReason": { - "value": "Incorrect name.", - "lang": "en" - }, - }, - "issuer": "did:example:ebfeb1f712ebc6f1c276e12ec21", - "issuanceDate": "2021-01-05T19:46:24Z", - "proof": {...} - }], -} -``` - -### 4. issuance {#issuance-message} - -- Type: `iota/issuance/0.1/issuance` -- Role: [issuer](#roles) - -The [issuer](#roles) transmits the signed credential following a [`issuance-response`](#issuance-response) by the [holder](#roles). The [issuer](#roles) may set an expiry until when they expect an acknowledgment and request a cryptographic signature in the acknowledgment for non-repudiation. - -#### Structure - -```json -{ - "signedCredential": Credential, // REQUIRED - "issuanceChallenge": { - "challenge": string, // REQUIRED - "credentialHash": string, // REQUIRED - }, // OPTIONAL - "issuanceExpiry": DateTime, // OPTIONAL -} -``` - -| Field | Description | Required | -| :----------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| [`signedCredential`][vc] | [Verifiable credential][vc] signed by the [issuer](#roles).[^1] | ✔ | -| `issuanceChallenge` | If present, indicates the [issuer](#issuer) requires the [issuance-acknowledgement](#issuance-acknowledgement) of the credential to be signed for non-repudiation. | ✖ | -| `challenge` | A random string that should be unique per [issuance](#issuance). | ✔ | -| `credentialHash` | The [Base58](https://tools.ietf.org/id/draft-msporny-base58-01.html)-encoded [SHA-256 digest](https://www.rfc-editor.org/rfc/rfc4634) of the `signedCredential`, including the `proof`, formatted according to the [JSON Canonicalization Scheme](https://tools.ietf.org/id/draft-rundgren-json-canonicalization-scheme-00.html). | ✔ | -| `issuanceExpiry` | A string formatted as an [XML Datetime](https://www.w3.org/TR/xmlschema11-2/#dateTime) normalized to UTC 00:00:00 and without sub-second decimal precision indicating when the offer expires. E.g: `"2021-12-30T19:17:47Z"`.[^2] | ✖ | - -[^1] The [holder](#roles) SHOULD validate both that the `proof` on the `signedCredential` is correctly signed by a trusted issuer and that the contents match those of the `unsignedCredential` from the [issuance-offer](#issuance-offer) they accepted. If not, a relevant problem-report should be sent. - -[^2] The [issuer](#roles) SHOULD send a problem-report if the `issuanceExpiry` datetime passes without receiving an [issuance-acknowledgement](#issuance-acknowledgement) message from the [holder](#roles). The [issuer](#roles) MAY revoke the credential in this case. - -#### Examples - -1. Issuing a credential including expiry and requesting proof: - -```json -{ - "unsignedCredential": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f", - "issuanceDate": "2021-01-05T19:37:24Z", - "credentialSubject": { - "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", - "degree": { - "type": "BachelorDegree", - "name": "Bachelor of Science and Arts" - } - }, - "proof": { - "type": "JcsEd25519Signature2020", - "verificationMethod": "did:example:ebfeb1f712ebc6f1c276e12ec21#key", - "signatureValue": "3KpeHSW4LybMy1smFEYriRmj5FsFfnxQiEsBnQdYzwkXMnjF3Jjn5RS1KGzheNpUgHW5yua8DoLbfYmZFAvaUVwv" - } - }, - "issuanceChallenge": { - "challenge": "6ff5f616-2f9c-4e47-b9d2-5553deeac01d", - "credentialHash": "21DtABsnYNb7oGEY8aybb9Bghq6NJJWvrQgtC2SBdhgQ8v6cZGjnT8RmEmBLZfHyfEYMAik3D1EoNQZCaT4RUKEX" - }, - "issuanceExpiry": "2021-01-05T20:07:24Z" -} -``` - -### 5. issuance-acknowledgment {#issuance-acknowledgment} - -- Type: `iota/issuance/0.1/issuance-acknowledgment` -- Role: [holder](#roles) - -The [holder](#roles) confirms receipt of a successful credential [`issuance`](#issuance-message), optionally including non-repudiable proof. - -#### Structure - -```json -{ - "signature": { - "issuanceChallenge": { - "challenge": string, // REQUIRED - "credentialHash": string, // REQUIRED - }, // REQUIRED - "proof": Proof, // REQUIRED - } // OPTIONAL -} -``` - -| Field | Description | Required | -| :---------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- | :------- | -| `signature` | This SHOULD be present if a `issuanceChallenge` was included in the preceding [`issuance`](#issuance-message) message.[^1] | ✖ | -| `issuanceChallenge` | This MUST match the `issuanceChallenge` in the preceding [`issuance`](#issuance-message) message. | ✔ | -| [`proof`](https://w3c-ccg.github.io/ld-proofs/) | Signature of the [holder](#roles) on the `issuanceChallenge`. | ✔ | - -[^1] The [issuer](#roles) MUST validate the `signature` and MAY revoke the issued credential if a `signature` was requested, e.g. for non-repudiation or auditing, and not received or an invalid `signature` is received. An explicit `signature` is used instead of a [signed DIDComm message](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message) to avoid the need to store the entire credential for auditing purposes as the hash is sufficient to prove a particular credential was accepted. - -#### Examples - -1. Acknowledge receipt of the credential: - -```json -{} -``` - -2. Acknowledge receipt of the credential including a signature: - -```json -{ - "signature": { - "issuanceChallenge": { - "challenge": "6ff5f616-2f9c-4e47-b9d2-5553deeac01d", - "credentialHash": "21DtABsnYNb7oGEY8aybb9Bghq6NJJWvrQgtC2SBdhgQ8v6cZGjnT8RmEmBLZfHyfEYMAik3D1EoNQZCaT4RUKEX", - }, - "proof": {...} - } -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :--------------------------------------------------------------- | :---------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `e.p.msg.iota.issuance.reject-request` | [issuance-request](#issuance-request) | [Issuer](#roles) rejects a credential request for any reason, e.g. unrecognised or invalid type, trusted issuer, or subject. | -| `e.p.msg.iota.issuance.reject-request.invalid-subject` | [issuance-request](#issuance-request) | [Issuer](#roles) rejects a credential request due to the `subject` being unrecognised, missing, or otherwise invalid. | -| `e.p.msg.iota.issuance.reject-request.invalid-type` | [issuance-request](#issuance-request) | [Issuer](#roles) rejects a credential request due to the `type` or `@context` being unsupported or otherwise invalid. | -| `e.p.msg.iota.issuance.reject-request.invalid-issuer` | [issuance-request](#issuance-request) | [Issuer](#roles) rejects a credential request due to `trustedIssuers` being unrecognised, unsupported or otherwise invalid. | -| `e.p.msg.iota.issuance.presentation-failed` | [issuance-offer](#issuance-offer) | [Issuer](#roles) terminates the protocol due to a failed [presentation](./presentation.mdx) request for more information prior to a [issuance-offer](#issuance-offer). | -| `e.p.msg.iota.issuance.reject-response.missing-signature` | [issuance-response](#issuance-response) | [Issuer](#roles) rejects an [issuance-response](#issuance-response) missing a `signature` when `offerChallenge` was included in the preceding [issuance-offer](#issuance-offer) message. | -| `e.p.msg.iota.issuance.reject-issuance` | [issuance](#issuance-message) | [Holder](#roles) rejects a credential issuance for any reason, e.g. mismatch with the credential in the [issuance-offer](#issuance-offer). Note that disputes are handled in [issuance-response](#issuance-response) prior to [issuance](#issuance-message). | -| `e.p.msg.iota.issuance.expired` | [issuance](#issuance-message) | [Issuer](#roles) notifies the [holder](#roles) that an [issuance](#issuance-message) message has expired without a valid [issuance-acknowledgement](#issuance-acknowledgement). | -| `e.p.msg.iota.issuance.reject-acknowledgement.missing-signature` | [issuance-acknowledgement](#issuance-acknowledgement) | [Issuer](#roles) rejects an [issuance-acknowledgement](#issuance-acknowledgement) missing a `signature` when `issuanceChallenge` was included in the preceding [issuance](#issuance-message) message. | - -## Unresolved Questions - -- The `credentialSubject::id` field of a verifiable credential is optional and not always a DID according to the [verifiable credential specification](https://www.w3.org/TR/vc-data-model). Should we enforce that it is always a DID? This affects presentations are noted in the [subject-holder relationships section of the specification](https://www.w3.org/TR/vc-data-model/#subject-holder-relationships). We essentially enforce the [`nonTransferable` property](https://www.w3.org/TR/vc-data-model/#nontransferable-property) for all credentials in our presentations currently to prevent verifiers storing and re-presenting credentials as their own. - -- `e.p.msg.iota.issuance.reject-request.invalid-type` and `e.p.msg.iota.issuance.reject-request.invalid-issuer` are specific to [CredentialType2021]. Should they be listed here? If yes, should they be marked accordingly? - -## Related Work - -- Aries Hyperledger: - - https://github.com/hyperledger/aries-rfcs/blob/08653f21a489bf4717b54e4d7fd2d0bdfe6b4d1a/features/0036-issue-credential/README.md - - https://github.com/hyperledger/aries-rfcs/blob/08653f21a489bf4717b54e4d7fd2d0bdfe6b4d1a/features/0453-issue-credential-v2/README.md - -## Further Reading - -- [Decentralized Identifiers (DIDs) 1.0](https://www.w3.org/TR/did-core/) -- [Verifiable Credentials Data Model 1.0](https://www.w3.org/TR/vc-data-model) -- [Verifiable Credentials Implementation Guidelines 1.0](https://w3c.github.io/vc-imp-guide/) - - - -[vc]: https://www.w3.org/TR/vc-data-model/#credentials -[subject]: https://www.w3.org/TR/vc-data-model/#credential-subject-0 -[credentialtype2021]: ../resources/credential-info.mdx#credentialtype2021 diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/post.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/post.mdx deleted file mode 100644 index aeeaf820430..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/post.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: Post -sidebar_label: Post ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -Allows the sending of a single message with arbitrary data. Multiple [post](#post-message) messages MAY be chained together in the same [DIDComm thread](https://identity.foundation/didcomm-messaging/spec/#threads) to achieve bi-directional communication. - -### Relationships - -- [Authentication](./authentication.mdx): can be used to authenticate both parties and establish [sender authenticated encryption](https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption). - -### Example Use-Cases - -- Instant messaging between two parties, where the text payload is displayed in a chat. -- IoT devices transmit sensor data to be aggregated in a central hub for processing. - -### Roles - -- Sender: sends the message. -- Receiver: receives the message. - -### Interaction - -![PostDiagram](/img/didcomm/post.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. post {#post-message} - -- Type: `iota/post/0.1/post` -- Role: [sender](#roles) - -The [sender](#roles) transmits a JSON `payload` to the [receiver](#roles). This MAY take advantage of [sender authenticated encryption](https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption) or be a [signed DIDComm message](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message) or both. - -#### Structure - -```json -{ - "payload": JSON // REQUIRED -} -``` - -| Field | Description | Required | -| :-------- | :-------------------------------------------------------------------- | :------- | -| `payload` | Any valid [JSON](https://datatracker.ietf.org/doc/html/rfc7159) text. | ✔ | - -#### Examples - -1. Send a single string: - -```json -{ - "payload": "Hello, world" -} -``` - -2. Send a single number: - -```json -{ - "payload": 42 -} -``` - -3. Send a JSON object: - -```json -{ - "payload": { - "status_code": 100, - "status": "Okay" - } -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :------------------------------ | :-------------------- | :------------------------------------------------------------------------- | -| `e.p.msg.iota.post.reject-post` | [post](#post-message) | [Receiver](#roles) rejects a [post](#post-message) message for any reason. | - -## Considerations - -Since the `payload` JSON structure is unrestricted, a [sender](#roles) cannot make assumptions about [receivers](#roles) being able to understand the `payload` in any meaningful way unless both parties have a shared implementation or pre-negotiate the `payload` structure. - -If complex and repeatable behaviour between parties is needed, implementors SHOULD define their own protocols with well-defined messages and interactions rather than using generic [post](#post-message) messages. - -## Related Work - -- Aries Hyperledger: https://github.com/hyperledger/aries-rfcs/blob/main/features/0095-basic-message/README.md diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/presentation.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/presentation.mdx deleted file mode 100644 index 7929dce0ff8..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/presentation.mdx +++ /dev/null @@ -1,388 +0,0 @@ ---- -title: Presentation -sidebar_label: Presentation ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -Allows presentation of one or more [verifiable credentials](https://www.w3.org/TR/vc-data-model) that are issued to a [holder](#roles) and are uniquely presented to a third-party [verifier](#roles) through [verifiable presentations](https://www.w3.org/TR/vc-data-model/#presentations). - -### Relationships - -- [Issuance](./issuance.mdx): a presentation may be used to provide extra information from the [holder](#roles) during a credential issuance. -- [Authentication](./authentication.mdx): a presentation may be used after authentication to prove the authenticated DID is bound to a physical identity. - -### Example Use-Cases - -- A company founder wants to prove they have a bank account in order to apply for insurance. -- A traveler proves to the border agency that they have a valid visa. -- An IoT device wants to prove who manufactured, installed, and benchmarked the device. - -### Roles - -- [Holder](https://www.w3.org/TR/vc-data-model/#dfn-holders): possesses one or more credentials that are combined in a verifiable presentation to show proof of ownership to the verifier. -- [Verifier](https://www.w3.org/TR/vc-data-model/#dfn-verifier): receives and validates the credentials presented by the holder. - -### Interaction - -![PresentationDiagram](/img/didcomm/presentation.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. presentation-offer {#presentation-offer} - -- Type: `iota/presentation/0.1/presentation-offer` -- Role: [holder](#roles) - -Sent by the [holder](#roles) to offer one or more credentials for a [verifier](#roles) to view. [`CredentialInfo`](../resources/credential-info.mdx) is used to indicate which kinds of credentials the [holder](#roles) wants to present. - -#### Structure - -```json -{ - "offers": [CredentialInfo], // REQUIRED - "requireSignature": bool, // OPTIONAL -} -``` - -| Field | Description | Required | -| :----------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `offers` | Array of one or more [`CredentialInfo`](../resources/credential-info.mdx), each specifying a single credential possessed by the holder.[^1] | ✔ | -| `requireSignature` | Request that the [verifier](#roles) use a [signed DIDComm message][sdm] for non-repudiation of the [`presentation-request`](#presentation-request). The [holder](#roles) SHOULD issue a `problem-report` if the [verifier](#roles) does not sign the message when this is `true`. Default: `false`. | ✖ | - -[^1] With [CredentialType2021], the `type` MAY be under-specified to preserve privacy but SHOULD always include the most general types. For example, a credential with the types `["VerifiableCredential", "DriversLicence", "EUDriversLicence", "GermanDriversLicence"]` could be specified as `["VerifiableCredential", "DriversLicence"]`. - -#### Examples - -1. Offer a single verifiable credential: - -```json -{ - "offers": [ - { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f" - } - ] -} -``` - -2. Offer two verifiable credentials with different issuers: - -```json -{ - "offers": [ - { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f" - }, - { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "https://example.edu/issuers/565049" - } - ] -} -``` - -### 2. presentation-request {#presentation-request} - -- Type: `iota/presentation/0.1/presentation-request` -- Role: [verifier](#roles) - -Sent by the [verifier](#roles) to request one or more verifiable credentials from a [holder](#roles). [`CredentialInfo`](../resources/credential-info.mdx) indicates which kinds of credentials the [verifier](#roles) wants presented by the [holder](#roles). - -[Verifiers](#roles) are RECOMMENDED to use a [signed DIDComm message][sdm]. [Holders](#roles) may choose to blocklist verifiers that refuse to provide signed requests. - -#### Structure - -```json -{ - "requests": [{ - "credentialInfo": CredentialInfo, // REQUIRED - "optional": bool // OPTIONAL - }], // REQUIRED - "challenge": string, // REQUIRED -} -``` - -| Field | Description | Required | -| :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `requests` | Array of one or more requests, each specifying a single credential possessed by the holder. | ✔ | -| `credentialInfo` | A [`CredentialInfo`](../resources/credential-info.mdx), specifying a credential requested by the verifier.[^1] | ✔ | -| `optional` | Whether this credential is required (`false`) or optional (`true`) to present by the holder. A holder SHOULD send a problem report if unable to satisfy a non-optional credential request. Default: `false`. | ✖ | -| [`challenge`](https://w3c-ccg.github.io/ld-proofs/#dfn-challenge) | A random string unique per [`presentation-request`](#presentation-request) by a verifier to help mitigate replay attacks. | ✔ | - -[^3] Verifiers are RECOMMENDED to include a proof whenever possible to avoid rejections from holders that enforce non-repudiation. Holders could use this to prove that a verifier is non-compliant with laws or regulations, e.g. over-requesting information protected by [GDPR](https://gdpr-info.eu/). Holders MAY still choose to accept unsigned [`presentation-requests`](#presentation-request) on a case-by-case basis, even if `requireSignature` was `true` in their [`presentation-offer`](#presentation-offer), as some verifiers may be unable to perform cryptographic signing operations. If the `proof` is invalid, the receiving holder MUST send a `problem-report`. - -#### Examples - -1. Request a single credential matching both specified types using [CredentialType2021]. - -```json -{ - "requests": [ - { - "credentialInfo": { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "UniversityDegreeCredential"] - } - } - ], - "challenge": "06da6f1c-26b0-4976-915d-670b8f407f2d" -} -``` - -2. Request a required credential using [CredentialType2021] from a particular trusted issuer and an optional credential. - -```json -{ - "requests": [ - { - "credentialInfo": { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "trustedIssuer": ["did:example:76e12ec712ebc6f1c221ebfeb1f"] - } - }, - { - "credentialInfo": { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "DriversLicence"] - }, - "optional": true - } - ], - "challenge": "06da6f1c-26b0-4976-915d-670b8f407f2d" -} -``` - -3. Request a single credential using [CredentialType2021] signed by one of several trusted issuers. - -```json -{ - "requests": [ - { - "credentialInfo": { - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "trustedIssuer": [ - "did:example:76e12ec712ebc6f1c221ebfeb1f", - "did:example:f1befbe122c1f6cbe217ce21e67", - "did:example:c6ef1fe11eb22cb711e6e227fbc" - ] - }, - "optional": false - } - ], - "challenge": "06da6f1c-26b0-4976-915d-670b8f407f2d" -} -``` - -### 3. presentation {#presentation} - -- Type: `iota/presentation/0.1/presentation` -- Role: [holder](#roles) - -Sent by the holder to present a [verifiable presentation][vp] of one or more [verifiable credentials](https://www.w3.org/TR/vc-data-model/#credentials) for a [verifier](#roles) to review. - -#### Structure - -```json -{ - "presentation": VerifiablePresentation // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| [`presentation`][vp] | Signed [verifiable presentation][vp] containing one or more [verifiable credentials](https://www.w3.org/TR/vc-data-model/#credentials) matching the [presentation-request](#presentation-request).[^1][^2] | ✔ | - -[^1] The [`proof`](https://www.w3.org/TR/vc-data-model/#proofs-signatures) section in `presentation` MUST include the `challenge` sent by the verifier in the preceding [`presentation-request`](#presentation-request). Revoked, disputed, or otherwise invalid presentations or credentials MUST result in a rejected [`presentation-result`](#presentation-result) sent back to the holder, NOT a separate [`problem-report`]. Other such as the message lacking [sender authenticated encryption][sae] SHOULD result in a separate [`problem-report`]. - -[^2] With [CredentialType2021], the included credentials SHOULD match all `type` fields and one or more `issuer` if included in the [`presentation-request`](#presentation-request). - -#### Examples - -1. Presentation of a verifiable presentation credential. - -```json -{ - "presentation": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "type": "VerifiablePresentation", - "verifiableCredential": [{ - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f", - "issuanceDate": "2021-05-03T19:73:24Z", - "credentialSubject": { - "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", - "degree": { - "type": "BachelorDegree", - "name": "Bachelor of Science and Arts" - } - }, - "proof": { ... } - }], - "proof": { - "challenge": "06da6f1c-26b0-4976-915d-670b8f407f2d", - ... - } - } -} -``` - -### 4. presentation-result {#presentation-result} - -- Type: `iota/presentation/0.1/presentation-result` -- Role: [verifier](#roles) - -Sent by the verifier to communicate the result of the presentation. It allows the verifier to raise disputes encountered in the verification. The message SHOULD be signed by the verifier for non-repudiation. - -Similar to [`presentation-request`](#presentation-request), [verifiers](#roles) are RECOMMENDED to use a [signed DIDComm message][sdm] whenever possible for non-repudiation of receipt of the presentation. [Holders](#roles) may choose to blocklist verifiers that refuse to provide signatures or do not send a [presentation-result](#presentation-result) at all. - -If the [presentation-result](#presentation-result) contains `disputes` or a problem report was issued, the protocol may be restarted to retry the presentation. [Verifiers](#roles) may choose to only request the failed credential kinds in the retry, retaining the accepted credentials from the failed presentation. - -#### Structure - -```json -{ - "accepted": bool, // REQUIRED - "disputes": [{ - "credentialId": string, // REQUIRED - "dispute": Dispute, // REQUIRED - }], // OPTIONAL -} -``` - -| Field | Description | Required | -| :----------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `accepted` | Indicates if the verifier accepted the [`presentation`](#presentation) and credentials. | ✔ | -| `disputes` | Array of disputes | ✖ | -| [`credentialId`](https://www.w3.org/TR/vc-data-model/#identifiers) | Identifier of the credential for which there is a dispute. If the credential lacks an `id` field, this should be a content-addressed identifier; we RECOMMEND the [SHA-256 digest](https://www.rfc-editor.org/rfc/rfc4634) of the credential. | ✔ | - -#### Examples - -1. Successful result: - -```json -{ - "accepted": true -} -``` - -2. Unsuccessful result disputing a credential's content: - -```json -{ - "accepted": false, - "disputes": [{ - "id": "http://example.com/credentials/123", - "dispute": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "id": "http://example.com/credentials/123", - "type": ["VerifiableCredential", "DisputeCredential"], - "credentialSubject": { - "id": "http://example.com/credentials/245", - "currentStatus": "Disputed", - "statusReason": { - "value": "Address is out of date.", - "lang": "en" - }, - }, - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f", - "issuanceDate": "2017-12-05T14:27:42Z", - "proof": { ... } - } - }], -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :---------------------------------------------------------------- | :-------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `e.p.msg.iota.presentation.reject-offer` | [presentation-offer](#presentation-offer) | [Verifier](#roles) rejects a presentation offer for any reason, e.g. unrecognised type or untrusted issuer. | -| `e.p.msg.iota.presentation.reject-offer.invalid-type` | [presentation-offer](#presentation-offer) | [Verifier](#roles) rejects a presentation offer due to a `type` or `@context` being unsupported or otherwise invalid. | -| `e.p.msg.iota.presentation.reject-offer.invalid-issuer` | [presentation-offer](#presentation-offer) | [Verifier](#roles) rejects a presentation offer due to `issuer` being unrecognised, untrusted or otherwise invalid. | -| `e.p.msg.iota.presentation.reject-offer.reject-require-signature` | [presentation-offer](#presentation-offer) | [Verifier](#roles) rejects a presentation offer due to being unable or unwilling to provide a signature for the following [presentation-request](#presentation-request) | -| `e.p.msg.iota.presentation.reject-request` | [presentation-request](#presentation-request) | [Holder](#roles) rejects a request for any reason. | -| `e.p.msg.iota.presentation.reject-request.invalid-type` | [presentation-request](#presentation-request) | [Holder](#roles) rejects a request due to a `type` or `@context` being unsupported or otherwise invalid. | -| `e.p.msg.iota.presentation.reject-request.invalid-issuer` | [presentation-request](#presentation-request) | [Holder](#roles) rejects a request due to a `issuer` being unsupported or otherwise invalid. | -| `e.p.msg.iota.presentation.reject-request.missing-signature` | [presentation-request](#presentation-request) | [Holder](#roles) rejects a request due to a missing signature from the [verifier](#roles). The [holder](#roles) may choose to blocklist [verifiers](#roles) that fail to sign requests. | -| `e.p.msg.iota.presentation.reject-presentation` | [presentation](#presentation) | [Verifier](#roles) rejects a presentation and abandons the protocol for any reason other than disputed verifiable credential content, which should instead be communicated via [presentation-result](#presentation-result). | -| `e.p.msg.iota.presentation.reject-result` | [presentation-result](#presentation-result) | [Holder](#roles) rejects a result for any reason. | -| `e.p.msg.iota.presentation.reject-result.missing-signature` | [presentation-result](#presentation-result) | [Holder](#roles) rejects a result due to a missing signature requested from the [verifier](#roles). The [holder](#roles) may blocklist the [verifier](#roles) from future requests. | -| `e.p.msg.iota.presentation.reject-retry` | [presentation-result](#presentation-result) | [Holder](#roles) chooses not to retry the presentation flow and terminates the protocol. | - -## Considerations - -This section is non-normative. - -- **Security**: implementors SHOULD transmit the presentation over an encrypted channel etc. [see authentication](./authentication.mdx). -- **Authentication**: it is RECOMMENDED to use either the [authentication protocol](./authentication.mdx) for once-off mutual authentication or to establish [sender-authenticated encryption][sae] for continuous authentication of both parties in the DIDComm thread. Signatures (`proof` fields) and [signed DIDComm messages][sdm] SHOULD NOT be relied upon for this in general: https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message -- **Authorisation**: establishing whether either party is allowed to request/offer presentations is an application-level concern. -- **Validation**: apart from verifying the presentation and credentials are signed by a trusted issuer, how credential subject matter fields are checked for disputes is out-of-scope. - -## Unresolved Questions - -- Is a `schema` field needed for the `presentation-offer` and `presentation-request` to identify the types of verifiable credentials and allow forward compatibility for different fields in the message? E.g. a `SelectiveDisclosure` or ZKP message may only offer or request certain fields in the credential. Does this relate to the [`credentialSchema`](https://www.w3.org/TR/vc-data-model/#data-schemas) field in credentials? -- Use `schemas` to negotiate generic form entries as a self-signed credential? E.g. could ask for username, preferred language, comments, any generic information not signed/verified by a third-party issuer from a generic wallet? Similar to Presentation Exchange? https://identity.foundation/presentation-exchange/spec/v1.0.0/ -- Identifiers (`id` field) are [optional in verifiable credentials](https://www.w3.org/TR/vc-data-model/#identifiers). The spec suggests content-addressed identifiers when the `id` is not available but their particulars are unclear as there is no spec referenced. This affects the `disputes` reported in the [`presentation-result`](#presentation-result). -- We should RECOMMENDED the `id` of a verifiable credential being a UUID (what version?) in issuance. Needs to be a URI https://www.w3.org/TR/vc-data-model/#identifiers, do UUIDs qualify? -- `e.p.msg.iota.presentation.reject-request.invalid-type`, `e.p.msg.iota.presentation.reject-request.invalid-issuer`, `e.p.msg.iota.presentation.reject-request.invalid-issuer` and `e.p.msg.iota.presentation.reject-request.invalid-type` are specific to [CredentialType2021]. Should they be listed here? If yes, should they be marked accordingly? - -## Related Work - -- Aries Hyperledger: https://github.com/hyperledger/aries-rfcs/tree/main/features/0454-present-proof-v2 -- Jolocom: https://jolocom.github.io/jolocom-sdk/1.0.0/guides/interaction_flows/#credential-verification -- Presentation Exchange: https://identity.foundation/presentation-exchange/spec/v1.0.0/ - -## Further Reading - -- [Decentralized Identifiers (DIDs) 1.0](https://www.w3.org/TR/did-core/) -- [Verifiable Credentials Data Model 1.0](https://www.w3.org/TR/vc-data-model) -- [Verifiable Credentials Implementation Guidelines 1.0](https://w3c.github.io/vc-imp-guide/) - - - -[vp]: https://www.w3.org/TR/vc-data-model/#presentations-0 -[sae]: https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption -[sdm]: https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message -[credentialtype2021]: ../resources/credential-info.mdx#credentialtype2021 diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation-options.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation-options.mdx deleted file mode 100644 index a8a28e91b9b..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation-options.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Revocation Options -sidebar_label: Revocation Options ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -Allows discovery of available [`RevocationInfo`](./revocation.mdx#RevocationInfo) types for use with the [revocation](./revocation.mdx) protocol. - -### Relationships - -- [revocation](./revocation.mdx): this protocol is used to discover the `revocationInfoType` options available to a [trusted-party](#roles) for use in a [revocation-request](./revocation.mdx#revocation-request). - -### Roles - -- Trusted-Party: requests supported methods of revocation. -- Revoker: offers supported methods of revocation. - -### Interaction - -![RevocationOptionsDiagram](/img/didcomm/revocation-options.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. revocation-options-request {#revocation-options-request} - -- Type: `iota/revocation-options/0.1/revocation-options-request` -- Role: [trusted-party](#roles) - -Empty message requesting all available [`RevocationInfo`](./revocation.mdx#RevocationInfo) types. - -#### Structure - -```json -{} -``` - -### 2. revocation-options {#revocation-options} - -- Type: `iota/revocation-options/0.1/revocation-options` -- Role: [revoker](#roles) - -Response including all available [RevocationInfo](./revocation.mdx#RevocationInfo) types supported by the [revoker](#roles). - -#### Structure - -```json -{ - "revocationInfoTypes": [string], // REQUIRED -} -``` - -| Field | Description | Required | -| :-------------------- | :----------------------------------------------------------------------------- | :------- | -| `revocationInfoTypes` | List of supported [RevocationInfo](./revocation.mdx#RevocationInfo) types.[^1] | ✔ | - -[^1] The actual list of supported types may be vague or exact depending on how much the [revoker](#roles) trusts the requester. The supported types may also differ per requester. - -#### Examples - -1. Response including multiple [RevocationInfo](./revocation.mdx#RevocationInfo) types: - -```json -{ - "revocationInfoTypes": [ - "KeyRevocation2021", - "CredentialRevocation2021", - "CredentialStatusRevocation2021" - ] -} -``` - -2. Response including a single [RevocationInfo](./revocation.mdx#RevocationInfo) type: - -```json -{ - "revocationInfoTypes": ["CredentialRevocation2021"] -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :----------------------------------------------- | :---------------------------------------- | :------------------------------------------------------ | -| `e.p.msg.iota.revocation-options.reject-request` | [revocation-options](#revocation-options) | The [revoker](#roles) rejects a request for any reason. | - -## Considerations - -This section is non-normative. - -- **Privacy**: similar to [discover features](https://github.com/decentralized-identity/didcomm-messaging/blob/9039564e143380a0085a788b6dfd20e63873b9ca/docs/spec-files/feature_discovery.mdx), this protocol could be used to fingerprint a party partially or reveal its capabilities. If privacy is a concern, implementors should take care to accept requests only from parties authorized to perform [revocation](./revocation.mdx) or return a subset/superset of its actual supported options. - -## Unresolved Questions - -- Should revocation-options include the credential status sub-types for `CredentialStatusRevocation2021`? diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation.mdx deleted file mode 100644 index f3540ea6c31..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/revocation.mdx +++ /dev/null @@ -1,289 +0,0 @@ ---- -title: Revocation -sidebar_label: Revocation ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-18 - -## Overview - -Allows to request revocation of an issued [verifiable credential](https://www.w3.org/TR/vc-data-model/), either by the holder or a trusted-party. If the revoker is unable to revoke the credential themselves, they may delegate the revocation to the issuer, in which case they take on the role of trusted-party in their request. - -### Relationships - -- [revocation-options](./revocation-options.mdx): this may be preceded by the the [revocation-options](./revocation-options.mdx) protocol for the [trusted-party](#roles) to discover the available [`RevocationInfo` types](#RevocationInfo). -- [presentation](./presentation.mdx): this may include a [presentation](./presentation.mdx) by the [revoker](#roles) to request additional information, such as the entire credential being revoked or authorization information. - -### Example Use-Cases - -- A member of an organisation asks the organisation to revoke their membership. -- A subsidiary of a company asks central to revoke a credential concerning one of their customers. - -### Roles - -- Trusted-Party: has the authority to request the revocation of verifiable credentials. May also be the holder of the credential but not necessarily. -- Revoker: able to revoke the verifiable credential. May also be the [issuer](https://www.w3.org/TR/vc-data-model/#dfn-issuers) of the credential but not necessarily. - -### Interaction - -![RevocationDiagram](/img/didcomm/revocation.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. revocation-request {#revocation-request} - -- Type: `iota/revocation/0.1/revocation-request` -- Role: [trusted-party](#roles) - -Sent by the [trusted-party](#roles) or holder to request revocation of an issued verifiable credential. This message conveys which credential should be revoked and which method should be used. The [revoker](#roles) MAY require this to be a [signed DIDComm message](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message) for auditing purposes and reject unsigned requests. - -#### Structure - -```json -{ - "revocationInfo": RevocationInfo, // REQUIRED -} -``` - -| Field | Description | Required | -| :---------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- | :------- | -| [`revocationInfo`](#RevocationInfo) | Contains information sufficient to specify which credential should be revoked. See [`revocationInfo`](#RevocationInfo).[^1] | ✔ | - -[^1] If an unsupported `revocationInfo` type is received, the [revoker](#roles) MUST issue a problem-report. The specific problem-report descriptor is `invalid-revocation-type` but if privacy is a concern, a [revoker](#roles) may send a more generic descriptor such as `reject-request` to avoid disclosing its capabilities more than the [revocation-options](./revocation-options.mdx#Considerations) protocol would reveal. - -#### Examples - -1. Request to revoke a credential by identifier using "CredentialRevocation2021": - -```json -{ - "revocationInfo": { - "revocationInfoType": "CredentialRevocation2021", - "credentialId": "0495e938-3cb7-4228-bb73-c642ec6390c8" - } -} -``` - -2. Request to revoke all credentials signed by a specific [verification method](https://w3c-ccg.github.io/lds-ed25519-2020/#verification-method) identified by `#keys2` using "KeyRevocation2021": - -```json -{ - "revocationInfo": { - "revocationInfoType": "KeyRevocation2021", - "key": "did:example:76e12ec712ebc6f1c221ebfeb1f#keys-2" - } -} -``` - -### 2. revocation-response {#revocation-response} - -- Type: `iota/revocation/0.1/revocation-response` -- Role: [revoker](#roles) - -Sent by the [revoker](#roles) as soon as the revocation is performed to indicate the current status. - -#### Structure - -```json -{ - "status": "revoked" | "pending", -} -``` - -| Field | Description | Required | -| :------- | :------------------------------------------------------------------- | :------- | -| `status` | Current status of the revocation, either `revoked` or `pending`.[^1] | ✔ | - -[^1] The status should be `revoked` if the credential or signing key is confirmed to be revoked, and `pending` if the revocation has been accepted but not yet performed or committed. For instance, a revocation that updates a DID document may require waiting for the update transaction to be confirmed, or it could be queued for a batch update. If the [revoker](#roles) is unable to perform the revocation or rejects the request for any reason, they MUST instead respond with a [`problem-report`](#problem-reports). Care should be taken not to reveal which credentials are under the control of the revoker to prevent privacy-revealing brute-force attacks. - -The [trusted-party](#roles) SHOULD verify that the credential is actually revoked after this message is received. The [revocation protocol](#Revocation) MAY be polled by a [trusted-party](#roles) by re-sending the same request to confirm revocation if the status of `pending` is received. In the case of a public ledger, however, the [trusted-party](#roles) can query the public state of the verification method themselves to confirm revocation. - -#### Examples - -1. Response to a [revocation-request](#revocation-request) where the [revoker](#roles) confirms revocation directly: - -```json -{ - "status": "revoked" -} -``` - -2. Response to a [revocation-request](#revocation-request) where the [revoker](#roles) confirms the revocation was scheduled, but can only be confirmed at a later point: - -```json -{ - "status": "pending" -} -``` - -## RevocationInfo {#RevocationInfo} - -The `RevocationInfo` object contains the information necessary for a [revoker](#roles) to revoke a verifiable credential. For instance, this may include the `id` field of the credential, in which case a [revoker](#roles) must maintain a map to the signing key used for each credential to revoke them. It could also be the identifier for the signing key itself on the DID document of the issuer. Implementors are free to construct their own `RevocationInfo` types as different singing schemes may require different information for revocation. - -Implementors MUST adhere to at least one of the types below, either [KeyRevocation2021](#keyrevocation2021) or [CredentialRevocation2021](#credentialrevocation2021). Implementors MAY define additional types as-needed. A valid `RevocationInfo` type MUST have a `revocationInfoType` field. - -### KeyRevocation2021 - -- Type: `KeyRevocation2021` - -Allows a particular cryptographic public key linked as a verification method to be specified for revocation. This may reference any singular verification method such as [Ed25519VerificationKey2018](https://www.w3.org/TR/did-spec-registries/#ed25519verificationkey2018) or [RsaVerificationKey2018](https://www.w3.org/TR/did-spec-registries/#rsaverificationkey2018). Verification methods that hold multiple keys as a collection could, for example, encode the index of the key to be revoked in the [query](https://www.w3.org/TR/did-core/#dfn-did-queries) of the [DIDUrl](https://www.w3.org/TR/did-core/#did-url-syntax). - -See the [DID Spec Registry for more verification method types](https://www.w3.org/TR/did-spec-registries/#verification-method-types). - -Note that revoking a verification method revokes all verifiable credentials signed with its key. - -#### Structure - -```json -{ - "revocationInfoType": string, // REQUIRED - "key": DIDUrl, // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `revocationInfoType` | String indicating the `RevocationInfo` type, MUST be `"KeyRevocation2021"`. | ✔ | -| `key` | String conforming to the [DIDUrl syntax](https://www.w3.org/TR/did-core/#did-url-syntax) identifying a [verification method](https://www.w3.org/TR/did-core/#verification-methods) to be revoked.[^1] | ✔ | - -[^1] the [fragment](https://www.w3.org/TR/did-core/#dfn-did-fragments) MUST reference a valid verification method. The DID document referenced need not belong to the revoker necessarily, as they could forward or delegate the request to the actual owner or controller. The [query](https://www.w3.org/TR/did-core/#dfn-did-queries) MAY include extra information needed to identify the particular signing key. - -#### Example - -1. Specify a single key or verification method to revoke: - -```json -{ - "revocationInfoType": "KeyRevocation2021", - "key": "did:example:76e12ec712ebc6f1c221ebfeb1f#keys-1" -} -``` - -### CredentialRevocation2021 - -- Type: `CredentialRevocation2021` - -Allows requesting the revocation of a verifiable credential by its identifier field. This implies that the revoker needs to keep track of the relevant method of revocation and additional information such as the verification method used to sign it to be able to revoke the credential. - -```json -{ - "revocationInfoType": string, // REQUIRED - "credentialId": string, // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `revocationInfoType` | String indicating the `RevocationInfo` type, MUST be `"CredentialRevocation2021"`. | ✔ | -| `credentialId` | A [URI](https://www.w3.org/TR/vc-data-model/#dfn-uri) corresponding to the [id property](https://www.w3.org/TR/vc-data-model/#identifiers) of a verifiable credential. | ✔ | - -#### Examples - -1. Specify the identifier of the credential to revoke: - -```json -{ - "revocationInfoType": "CredentialRevocation2021", - "credentialId": "1dd5bbc6-b0bc-4f82-94a9-c723e11075b5" -} -``` - -### CredentialStatusRevocation2021 - -- Type: `CredentialStatusRevocation2021` - -Request the revocation of a verifiable credential by sending its corresponding [credential status](https://www.w3.org/TR/vc-data-model/#status) information. The [revoker](#roles) should ensure that this information is correct and that the requester is authorized. - -```json -{ - "revocationInfoType": string, // REQUIRED - "credentialStatus": CredentialStatus, // REQUIRED -} -``` - -| Field | Description | Required | -| :---------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :------- | -| `revocationInfoType` | String indicating the `RevocationInfo` type, MUST be `"CredentialStatusRevocation2021"`. | ✔ | -| [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) | A [credential status](https://www.w3.org/TR/vc-data-model/#status) object.[^1] | ✔ | - -[^1] This SHOULD correspond with one of the supported credential status methods in the [verifiable credentials extension registry](https://w3c-ccg.github.io/vc-extension-registry/#status-methods). - -#### Examples - -1. Specifying a [Credential Status List 2017](https://w3c-ccg.github.io/vc-csl2017/) entry: - -```json -{ - "revocationInfoType": "CredentialStatusRevocation2021", - "credentialStatus": { - "id": "https://example.edu/status/24", - "type": "CredentialStatusList2017" - } -} -``` - -2. Specifying a [Revocation List 2020](https://w3c-ccg.github.io/vc-status-rl-2020/) entry: - -```json -{ - "revocationInfoType": "CredentialStatusRevocation2021", - "credentialStatus": { - "id": "https://dmv.example.gov/credentials/status/3#94567", - "type": "RevocationList2020Status", - "revocationListIndex": "94567", - "revocationListCredential": "https://example.com/credentials/status/3" - } -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :--------------------------------------------------------------- | :---------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `e.p.msg.iota.revocation.reject-request` | [revocation-request](#revocation-request) | The [revoker](#roles) rejects a request for any reason, e.g. the revoker does not have the authority to revoke the particular credential or key, or a relayed revocation request to another [revoker](#roles) failed. | -| `e.p.msg.iota.revocation.reject-request.invalid-revocation-type` | [revocation-request](#revocation-request) | The [revoker](#roles) rejects a request due to an unrecognised, unsupported, or otherwise invalid `revocationInfoType`. | -| `e.p.msg.iota.revocation.reject-request.invalid-revocation-info` | [revocation-request](#revocation-request) | The [revoker](#roles) rejects a request due to a malformed or otherwise invalid `revocationInfo`. | -| `e.p.msg.iota.revocation.presentation-failed` | [revocation-request](#revocation-request) | The [revoker](#roles) terminates the protocol due to a failed presentation from the [trusted-party](#roles), e.g. failed to prove permission to revoke the particular credential. | - -## Considerations - -This section is non-normative. - -The revoker needs to check if the credential may actually be revoked and if the trusted party actually has the authority to request the revocation. - -## Unresolved Questions - -- Should the trusted party be able to prove that the revoker claimed to have revoked the credential by making him include a signature in the `revocation-response`, or is it sufficient that they can query the signing key or revocation material in the case of a public ledger? -- Should revocation-options include the credential status sub-types for `CredentialStatusRevocation2021`? -- Separate revocation-notification (https://github.com/hyperledger/aries-rfcs/blob/main/features/0183-revocation-notification/README.mdx) flow for notifying the holder that their credential was revoked, optionally including the reason? Dual entry for a holder to request the revocation reason? -- Include reason-code/reason-comment in the request? Could be used by the revoker for auditing/validating the request but overall seems not useful - trusted-party would store those reasons internally, holder comments aren't very useful. Can be achieved via embedded presentation and self-signed credentials? - -## Related Work - -- Aries Hyperledger: https://github.com/hyperledger/aries-rfcs/blob/main/features/0183-revocation-notification/README.md - -## Further Reading - -- https://www.w3.org/TR/vc-data-model/ -- https://hyperledger-indy.readthedocs.io/projects/hipe/en/latest/text/0011-cred-revocation/README.html diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/signing.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/signing.mdx deleted file mode 100644 index d4221648aee..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/signing.mdx +++ /dev/null @@ -1,216 +0,0 @@ ---- -title: Signing -sidebar_label: Signing ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -Allows a trusted-party to request the signing of an unsigned verifiable credential by an issuer. - -### Relationships - -- [Issuance](./issuance.mdx): an [issuer](./issuance.mdx#roles) may take on the role of [trusted-party](#roles) to request a different [issuer](#roles) to sign a new credential. - -### Example Use-Cases - -- A separate department requests a signature by the legal department of a company. -- A subsidiary requests the parent company to sign a credential. -- An IOT device generates an unsigned credential and requests a secure server to sign it. - -### Roles - -- Trusted-Party: trusted by the issuer to generate unsigned credentials asserting claims about one or more subjects. -- [Issuer](https://www.w3.org/TR/vc-data-model/#dfn-issuers): has the capability to cryptographically sign credentials. - -### Interaction - -![SigningDiagram](/img/didcomm/signing.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. signing-request {#signing-request} - -- Type: `iota/signing/0.1/signing-request` -- Role: [trusted-party](#roles) - -Request by a [trusted-party](#roles) for an [issuer](#roles) to sign a credential. - -To authenticate the [trusted-party](#roles), this SHOULD be sent using [sender authenticated encryption][sae] established in a preceding [authentication](./authentication.mdx) protocol. For non-repudiation or auditing, the [issuer](#role) MAY enforce that the [signing-request](#signing-request) be a [signed DIDComm message][sdm]. - -#### Structure - -```json -{ - "unsignedCredential": Credential // REQUIRED -} -``` - -| Field | Description | Required | -| :------------------------- | :--------------------------------------------------------------------------------------- | :------- | -| [`unsignedCredential`][vc] | Unsigned [verifiable credential][vc] requested to be signed by the [issuer](#roles).[^1] | ✔ | - -[^1] The initial credential MUST NOT have a `proof` section. - -#### Examples - -1. Request to sign a bachelors degree. - -```json -{ - "unsignedCredential": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f", - "issuanceDate": "2021-05-03T19:73:24Z", - "credentialSubject": { - "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", - "degree": { - "type": "BachelorDegree", - "name": "Bachelor of Science and Arts" - } - } - } -} -``` - -### 2. signing-response {#signing-response} - -- Type: `iota/signing/0.1/signing-response` -- Role: [issuer](#roles) - -Response from the [issuer](#roles) returning the signed credential back to the [trusted-party](#roles). - -#### Structure - -```json -{ - "signedCredential": Credential // REQUIRED -} -``` - -| Field | Description | Required | -| :----------------------- | :--------------------------------------------------------------------------------------- | :------- | -| [`signedCredential`][vc] | Signed [verifiable credential][vc] matching the [signing-request](#signing-request).[^1] | ✔ | - -[^1] The [trusted-party](#roles) MUST validate the signature in the `proof` section and issue a problem-report if invalid. The [trusted-party](#roles) SHOULD also verify that the contents of the `signedCredential` sent back by the [issuer](#roles) are complete and unaltered from the [signing-request](#signing-request). - -The [issuer](#roles) may request in turn that the credential be signed by a different issuer unknown to the [trusted-party](#roles), by repeating this protocol or through alternative means. In such a case, it is up to the initial [trusted-party](#roles) whether or not to accept the final signature if not signed by the initial [issuer](#roles) they requested. - -#### Examples - -1. Respond with a signed a bachelors degree. - -```json -{ - "signedCredential": { - "@context": [ - "https://www.w3.org/2018/credentials/v1", - "https://www.w3.org/2018/credentials/examples/v1" - ], - "id": "6c1a1477-e452-4da7-b2db-65ad0b369d1a", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": "did:example:76e12ec712ebc6f1c221ebfeb1f", - "issuanceDate": "2021-05-03T19:73:24Z", - "credentialSubject": { - "id": "did:example:ebfeb1f712ebc6f1c276e12ec21", - "degree": { - "type": "BachelorDegree", - "name": "Bachelor of Science and Arts" - } - }, - "proof": {...} - } -} -``` - -### 3. signing-acknowledgement {#signing-acknowledgement} - -- Type: `iota/signing/0.1/signing-acknowledgement` -- Role: [trusted-party](#roles) - -Acknowledgement by the [trusted-party](#roles) that the credential was received and accepted. The [issuer](#roles) MAY revoke the credential if no acknowledgement is received. For auditing or non-repudiation the [issuer](#roles) MAY require that the [signing-acknowledgement](#signing-acknowledgement) be a [signed DIDComm message][sdm]. - -#### Structure - -```json -{ - "accepted": bool // REQUIRED -} -``` - -| Field | Description | Required | -| :--------- | :--------------------------------------------------------------------------------------------------- | :------- | -| `accepted` | Indicates that the `signedCredential` was received and validated by the [trusted-party](#roles).[^1] | ✔ | - -[^1] `accepted` MUST be `true`. Invalid signatures or credentials SHOULD result in problem-reports by the [trusted-party](#roles). - -#### Examples - -1. Accept the credential. - -```json -{ - "accepted": true -} -``` - -### Problem Reports {#problem-reports} - -The following problem-report codes may be raised in the course of this protocol and are expected to be recognised and handled in addition to any general problem-reports. Implementers may also introduce their own application-specific problem-reports. - -For guidance on problem-reports and a list of general codes see [problem reports](../resources/problem-reports.mdx). - -| Code | Message | Description | -| :------------------------------------- | :------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `e.p.msg.iota.signing.reject-request` | [signing-request](#signing-request) | The [issuer](#roles) rejects a signing request for any reason, e.g. malformed credential, unrecognised credential type, or unwillingness to sign the specific credential for the [trusted-party](#roles). | -| `e.p.msg.iota.signing.reject-response` | [signing-response](#signing-response) | The [trusted-party](#roles) rejects a signing response for any reason, e.g. mismatch between request and response credentials. | - -## Unresolved Questions - -- Using a signed DIDComm message for auditing requires retaining the entire message including the credential itself. While this may be desired or required for some purposes, it could complicate or violate GDPR laws. Should an explicit signature of the credential hash be used instead, similar to the [issuance](./issuance.mdx) protocol? - -## Considerations - -This section is non-normative. - -- **Security**: implementors SHOULD transmit credentials over an encrypted channel to prevent leaking sensitive information on subjects. See [sender-authenticated encryption][sae]. -- **Authentication**: it is RECOMMENDED to use sender-authenticated encryption for continuous authentication of both parties in the DIDComm thread. Anonymous encryption and/or once-off authentication may be insufficient. -- **Authorisation**: the [issuer](#roles) should establish whether a trusted-party is allowed to request signing of a particular credential or at all. -- **Validation**: apart from verifying the proof on the signed credential returned in the [signing-response](#signing-response), how the [issuer](#roles) validates the contents of a well-formed credential from a [trusted-party](#roles) and chooses whether or not to sign it is out-of-scope. - -## Related Work - -- Aries Hyperledger: https://github.com/hyperledger/aries-rfcs/tree/08653f21a489bf4717b54e4d7fd2d0bdfe6b4d1a/features/0327-crypto-service - -## Further Reading - -- [Verifiable Credentials Data Model 1.0](https://www.w3.org/TR/vc-data-model) - - - -[vc]: https://www.w3.org/TR/vc-data-model/#credentials -[sae]: https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption -[sdm]: https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/termination.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/termination.mdx deleted file mode 100644 index b769559b814..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/protocols/termination.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Termination -sidebar_label: Termination ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Version: 0.1 -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -## Overview - -Indicates the graceful termination of a connection. It is expected that no reconnection attempt will be made on any of the message thread/s in this connection following termination. This provides a chance for the receiver to clean up or archive any resources allocated to the connection. - -### Relationships - -- [Connection](./connection.mdx): this protocol terminates a communication initiated by the [connection protocol](./connection.mdx). - -### Example Use-Cases - -- A verifier terminates the connection following a successful presentation from a holder. -- One participant experiences an error and terminates the connection gracefully after sending a problem-report. - -### Roles - -- Sender: initiates the connection termination. -- Receiver: is notified of the termination. - -### Interaction - -![TerminationDiagram](/img/didcomm/termination.drawio.svg) - -
- - - For guidance on diagrams see the{' '} - corresponding section in the overview. - - -
- -## Messages - -### 1. termination {#termination} - -- Type: `iota/termination/0.1/termination` -- Role: [sender](#roles) - -Used to inform the [receiver](#roles) that the [sender](#roles) wishes to terminate the established connection. - -#### Structure - -```json -{} -``` - -### 2. termination-response {#termination-response} - -- Type: `iota/termination/0.1/termination-response` -- Role: [receiver](#roles) - -Response from the [receiver](#roles) that the request to terminate the connection was acknowledged. MUST be sent if the field [`please_ack`](https://identity.foundation/didcomm-messaging/spec/#acks) is present in the [termination](#termination) message. - -#### Structure - -```json -{} -``` - -## Considerations - -This section is non-normative. - -- Which party terminates a connection depends on the application but is usually the same as the one that initiated it following a successful interaction to achieve. -- Any party may terminate a connection at any time, even during a protocol. -- A termination message indicates a graceful end to a connection but the underlying transport layer connection could terminate without this message. Implementors should implement reasonable timeouts and reconnection capabilities. - -## Related Work - -- Aries Hyperledger: https://github.com/hyperledger/aries-rfcs/blob/main/features/0030-sync-connection/abandon-connection-protocol/README.md diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/resources/credential-info.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/resources/credential-info.mdx deleted file mode 100644 index d53199b1498..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/resources/credential-info.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: CredentialInfo -sidebar_label: CredentialInfo ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -`CredentialInfo` objects allow parties to negotiate which kinds of [verifiable credentials][vc] they want to issue or exchange. [Verifiable credential][vc] kinds can be described by different attributes such as the [`type`](https://www.w3.org/TR/vc-data-model/#types) and [`@context`](https://www.w3.org/TR/vc-data-model/#contexts) fields or the structure of the data in the payload. `CredentialInfo` provides methods to specify the identifying characteristics of a credential. - -Currently, only `CredentialType2021` is prescribed but additional `CredentialInfo` methods may be introduced in the future, e.g. to account for selective disclosure of particular fields. If full schema negotiation of credentials is required, refer to the external [Presentation Exchange 1.0 specification](https://identity.foundation/presentation-exchange/spec/v1.0.0/). - -### CredentialType2021 - -- Type: `CredentialType2021` - -Negotiates [verifiable credentials][vc] using their [`type`][type] and optional [JSON-LD][json-ld] [`@context`][context]. The [`issuer`][issuer] field may also be included depending on the protocol and usage. - -```json -{ - "credentialInfoType": string, // REQUIRED - "@context": [string], // OPTIONAL - "type": [string], // REQUIRED - "issuer": [string], // OPTIONAL -} -``` - -| Field | Description | Required | -| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | -| `credentialInfoType` | String indicating the `CredentialInfo` method, MUST be `"CredentialType2021"`. | ✔ | -| [`@context`][context] | Array of [JSON-LD] [contexts][context] referenced in the credential. | ✖ | -| [`type`][type] | Array of credential [types][type] specifying the kind of credential offered.[^1] | ✔ | -| [`issuer`][issuer] | Array of credential [issuer][issuer] [DIDs](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers) or [URIs](https://www.w3.org/TR/vc-data-model/#dfn-uri).[^2] | ✖ | - -[^1] The [`type`][type] MAY be under-specified depending on the protocol but SHOULD always include the most general types. For example, a credential with the types `["VerifiableCredential", "DriversLicence", "EUDriversLicence", "GermanDriversLicence"]` could be specified as `["VerifiableCredential", "DriversLicence"]`. - -[^2] The [`issuer`][issuer] field MAY either be the single issuer of an existing credential, one or more issuers that a [verifier](../protocols/presentation.mdx#roles) would trust during a [presentation](../protocols/presentation.mdx), or one or more trusted issuers that a [holder](../protocols/issuance.mdx#roles) requests to sign their credential during an [issuance](../protocols/issuance.mdx). The [`issuer`][issuer] field is OPTIONAL as the [holder](../protocols/presentation.mdx#roles) may not want to reveal too much information up-front about the exact credentials they possess during a [presentation](../protocols/presentation.mdx); they may want a non-repudiable signed request from the verifier first. - -#### Examples - -1. Indicate a "UniversityDegreeCredential" from a specific issuer: - -```json -{ - "credentialInfoType": "CredentialType2021", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "issuer": ["did:example:76e12ec712ebc6f1c221ebfeb1f"] -} -``` - -## Unresolved Questions - -- Should we implement https://w3c-ccg.github.io/vp-request-spec/ as a `CredentialInfo`? -- Should we implement https://identity.foundation/presentation-exchange/spec/v1.0.0/ as a `CredentialInfo`? - -[vc]: https://www.w3.org/TR/vc-data-model -[json-ld]: https://json-ld.org/ -[context]: https://www.w3.org/TR/vc-data-model/#contexts -[type]: https://www.w3.org/TR/vc-data-model/#types -[issuer]: https://www.w3.org/TR/vc-data-model/#issuer diff --git a/docs/build/identity.rs/0.6/docs/specs/didcomm/resources/problem-reports.mdx b/docs/build/identity.rs/0.6/docs/specs/didcomm/resources/problem-reports.mdx deleted file mode 100644 index c5b9429f2e2..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/didcomm/resources/problem-reports.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Problem Reports -sidebar_label: Problem Reports ---- - -:::info - -The IOTA DIDComm Specification is in the RFC phase and may undergo changes. Suggestions are welcome at [GitHub #464](https://github.com/iotaledger/identity.rs/discussions/464). - -::: - -- Status: `IN-PROGRESS` -- Last Updated: 2021-10-29 - -[Problem reports](https://identity.foundation/didcomm-messaging/spec/#problem-reports) are a standard [DIDComm](https://identity.foundation/didcomm-messaging/spec/) feature for reporting errors or warnings between parties. Using this mechanism is not a general requirement but it is a best practice for relaying informative errors and may improve human experience. - -## Example - -A problem report is a standard DIDComm message: - -```json -{ - "type": "https://didcomm.org/report-problem/2.0/problem-report", - "id": "7c9de639-c51c-4d60-ab95-103fa613c805", - "pthid": "1e513ad4-48c9-444e-9e7e-5b8b45c5e325", - "body": { - "code": "e.p.xfer.cant-use-endpoint", - "comment": "Unable to use the {1} endpoint for {2}.", - "args": ["https://agents.r.us/inbox", "did:sov:C805sNYhMrjHiqZDTUASHg"], - "escalate_to": "mailto:admin@foo.org" - } -} -``` - -Note that problem reports may still use [sender authenticated encryption](https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption) or even be [signed DIDComm messages](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message). - -## IOTA Problem Codes - -We follow the notation for [problem codes defined by the DIDComm specification](https://github.com/decentralized-identity/didcomm-messaging/blob/84e5a7c66c87440d39e93df81e4440855273f987/docs/spec-files/problems.md#problem-codes). In general, we use the error sorter `e` and protocol scope `p` to indicate that problem reports result in the abandonment of a protocol. - -In addition to the [problem report descriptors in the DIDComm specification](https://github.com/decentralized-identity/didcomm-messaging/blob/84e5a7c66c87440d39e93df81e4440855273f987/docs/spec-files/problems.md#descriptors), we define the following non-exhaustive list of general problem report codes that may be sent during the course of any protocol: - -| Code | Description | -| :--------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `e.p.msg.invalid-message` | The message is malformed or fails field constraints validation. | -| `e.p.msg.unsupported-message` | The message type is unrecognised or unsupported by the recipient. | -| `e.p.msg.invalid-state` | The recipient is unable to handle the type of message in its current state. Typically when an unexpected message is received in the middle of a protocol on the same thread. | -| `e.p.msg.trust.not-authenticated` | The sender is required to authenticate to perform the requested action. | -| `e.p.msg.trust.not-authorised` | The sender is authenticated but lacks sufficient permissions to perform the requested action. | -| `e.p.msg.trust.not-sender-authenticated` | The recipient requires the message to use [sender authenticated encryption](https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption). | -| `e.p.msg.trust.not-encrypted` | The recipient requires the message to use [anonymous encryption](https://identity.foundation/didcomm-messaging/spec/#anonymous-encryption) | -| `e.p.msg.trust.not-signed` | The recipient requires a [signed DIDComm message](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message). | -| `e.p.msg.trust.crypto` | Any general cryptography-related error. E.g. the signature in a message payload or on a [signed DIDComm message](https://identity.foundation/didcomm-messaging/spec/#didcomm-signed-message) fails validation, or [sender authenticated encryption](https://identity.foundation/didcomm-messaging/spec/#sender-authenticated-encryption) fails. | -| `e.p.req.time` | The party has timed out waiting for a response. | - -These messages may be raised during or between protocols to inform the other party that something went wrong. A problem report with the error sorter `e` and protocol scope `p` terminates the protocol on the current thread and MAY be followed by a connection [termination](../protocols/termination.mdx). - -## Unresolved Questions - -- Should we support the message scope `m` to allow resending / retrying individual messages? - -## Further Reading - -- [DIDComm Problem Reports](https://identity.foundation/didcomm-messaging/spec/#problem-reports) diff --git a/docs/build/identity.rs/0.6/docs/specs/overview.mdx b/docs/build/identity.rs/0.6/docs/specs/overview.mdx deleted file mode 100644 index ea6abe12914..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/overview.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -title: Specifications Overview -sidebar_label: Overview -description: Provide overview of the specifications -image: /img/Identity_icon.png -keywords: - - specifications ---- - -While IOTA Identity implements many existing standards, it also adds some additional features we would like to standardize ourselves. This chapter covers these features and how they work in great detail. These are not light reads and can be skipped. - -The current specifications are: - -- [IOTA DID](./did/overview.mdx): The specification for the IOTA DID Method implemented on the Tangle. -- [IOTA DIDComm](./didcomm/overview.mdx): A collection of DIDComm protocols for common SSI interactions. -- [Revocation Bitmap 2022](./revocation_bitmap_2022.mdx): The specification for an on-Tangle credential revocation mechanism. diff --git a/docs/build/identity.rs/0.6/docs/specs/revocation_bitmap_2022.mdx b/docs/build/identity.rs/0.6/docs/specs/revocation_bitmap_2022.mdx deleted file mode 100644 index c2662f9c319..00000000000 --- a/docs/build/identity.rs/0.6/docs/specs/revocation_bitmap_2022.mdx +++ /dev/null @@ -1,201 +0,0 @@ ---- -title: Revocation Bitmap -sidebar_label: Revocation Bitmap -description: The specification for the embedded revocation bitmap. -image: /img/Identity_icon.png -keywords: - - DID - - specs - - specifications - - revocation - - bitmap ---- - -# Revocation Bitmap 2022 - -## Abstract - -This specification describes an on-Tangle mechanism for publishing the revocation status of [Verifiable Credentials](../concepts/verifiable_credentials/overview.mdx) embedded in an issuer's DID document. - -## Introduction - -Revocation gives an issuer the capability to invalidate a credential they issued before its natural expiration date. To achieve this, issuers can embed an identifier in the `credentialStatus` field of a credential. Verifiers can then lookup that identifier in a separate list, to check whether the credential is still valid. This document specifies a mechanism of embedding such a list, in form of a bitmap, in the DID document of the issuer, where each bitmap index corresponds to a credential they have issued. This mechanism is space-efficient and enables a verifier to check a credential's status in a privacy-preserving manner and without requiring additional lookups or external resources. - -## Revocation Bitmap Concept - -The revocation status of a verifiable credential is expressed as a binary value. The issuer keeps a bitmap of indices corresponding to verifiable credentials they have issued. If the binary value of the index in the bitmap is 1 (one), the verifiable credential is revoked, if it is 0 (zero) it is not revoked. - -## Data Model - -### Revocation Bitmap Status - -For an issuer to enable verifiers to check the status of a verifiable credential, the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) property MUST be specified with the following properties: - -| Property | Description | -| :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | The constraints on the `id` property are listed in the [Verifiable Credentials Data Model specification](https://www.w3.org/TR/vc-data-model/). The `id` MUST be a [DID URL](https://www.w3.org/TR/did-core/#did-url-syntax) that resolves to a [Revocation Bitmap Service](#revocation-bitmap-service) in the DID Document of the issuer. | -| `type` | The `type` property MUST be `"RevocationBitmap2022"`. | -| `revocationBitmapIndex` | The `revocationBitmapIndex` property MUST be an unsigned, 32-bit integer expressed as a string. This is the index of the credential in the issuer's revocation bitmap. Each index SHOULD be unique among all credentials linking to the same [Revocation Bitmap Service](#revocation-bitmap-service). | - -#### Example - -An example of a verifiable credential with a `credentialStatus` of type `RevocationBitmap2022`. - -```json -{ - "@context": "https://www.w3.org/2018/credentials/v1", - "id": "https://example.edu/credentials/3732", - "type": ["VerifiableCredential", "UniversityDegreeCredential"], - "credentialSubject": { - "id": "did:iota:B8DucnzULJ9E8cmaReYoePU2b7UKE9WKxyEVov8tQA7H", - "GPA": "4.0", - "degree": "Bachelor of Science and Arts", - "name": "Alice" - }, - "issuer": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", - "issuanceDate": "2022-06-13T08:04:36Z", - "credentialStatus": { - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", - "type": "RevocationBitmap2022", - "revocationBitmapIndex": "5" - }, - "proof": { - "type": "JcsEd25519Signature2020", - "verificationMethod": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#key-1", - "signatureValue": "2eHdbDumMrer4pNVkaiYMqsVqVp2adq7bRcgTJZiw17Zeghk2ZT49YHwLwCCg35YKganBhxP6YSbzYoBK1AuCUv" - } -} -``` - -### Revocation Bitmap Service - -To allow verifiers to check the status of a [Revocation Bitmap Status](#revocation-bitmap-status), the DID document of the credential issuer MUST contain a [service](https://www.w3.org/TR/did-core/#services) with the following properties: - -| Property | Description | -| :---------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | The constraints on the `id` property are listed in the [DID Core service specification](https://www.w3.org/TR/did-core/#services). The `id` property MUST be a DID URL uniquely identifying the revocation bitmap. | -| `type` | The `type` property MUST be `"RevocationBitmap2022"`. | -| `serviceEndpoint` | The `serviceEndpoint` MUST be generated according to the [service endpoint generation algorithm](#service-endpoint-generation-algorithm). | - -#### Example - -An example of an issuer's DID document where credential `"5"` in the `#revocation` service is revoked: - -```json -{ - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", - "verificationMethod": [ - { - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#key-1", - "controller": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z3hgM9fNkhwgT5mECbj1HdKoFNZgpffwQYEV8WBVHphXq" - } - ], - "capabilityInvocation": [ - { - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#sign-0", - "controller": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw", - "type": "Ed25519VerificationKey2018", - "publicKeyMultibase": "z83F6zbD3KqaxvQhqo25LvSXzoDdpZmp3EpPVonSVACwZ" - } - ], - "service": [ - { - "id": "did:iota:EvaQhPXXsJsGgxSXGhZGMCvTt63KuAFtaGThx6a5nSpw#revocation", - "type": "RevocationBitmap2022", - "serviceEndpoint": "data:application/octet-stream;base64,ZUp5ek1tQmdZR1NBQUFFZ1ptVUFBQWZPQUlF" - } - ] -} -``` - -## Algorithms - -The following algorithms define how to generate, expand and validate revocation bitmaps. - -### Service Endpoint Generation Algorithm - -The following process MUST be followed when producing a `RevocationBitmap2022` to embed in a service endpoint: - -1. Let **bitmap** be a [_roaring bitmap_](https://roaringbitmap.org/) where each bit is initialized to 0. -2. For each revoked credential with an **index** not exceeding an unsigned, 32-bit integer, set the corresponding bit in **bitmap** at **index** to 1. -3. Generate the **bitmap serialization** according to the [roaring bitmap serialization format](https://github.com/RoaringBitmap/RoaringFormatSpec/) using the **bitmap** as input. -4. Generate a **compressed bitmap** by using the ZLIB compression algorithm [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] on the **bitmap serialization** and base64-encoding [[RFC4648](https://datatracker.ietf.org/doc/html/rfc4648)] the result. -5. Create the **service endpoint** by embedding the **compressed bitmap** in a data URL [[RFC2397](https://datatracker.ietf.org/doc/html/rfc2397)]. On the data url, the `` MUST be `application/octet-stream` and the `base64` attribute MUST be set. -6. Return the **service endpoint**. - -### Service Endpoint Expansion Algorithm - -The following process MUST be followed when expanding the endpoint from a service of type `RevocationBitmap2022`: - -1. Let **service endpoint** be a data url generated using the [service endpoint generation algorithm](#service-endpoint-generation-algorithm). -2. The `` of the **service endpoint** MUST be `application/octet-stream` and the `base64` attribute MUST be set, return an error otherwise. Let **compressed bitmap** be the `` part of the data url. -3. Generate an **uncompressed bitmap** by base64-decoding [[RFC4648](https://datatracker.ietf.org/doc/html/rfc4648)] the **compressed bitmap** and then decompressing the result using ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)]. -4. Generate the **bitmap** by deserializing the **uncompressed bitmap** according to the [roaring bitmap serialization format](https://github.com/RoaringBitmap/RoaringFormatSpec/). -5. Return the **bitmap**. - -### Validation Algorithm - -The following steps MUST be followed when checking whether a verifiable credential is revoked: - -1. Let **credential** be a verifiable credential containing a `credentialStatus` whose `type` is `RevocationBitmap2022`. -2. Let **revocation bitmap URL** be the `id` field of the **credential**'s `credentialStatus`. -3. Resolve the **revocation bitmap URL** to a **revocation bitmap service** in the issuer's DID document, and verify that the service `type` is `RevocationBitmap2022`. Return an error otherwise. -4. Expand the endpoint of the **revocation bitmap service** into a **revocation bitmap** according to the [service endpoint expansion algorithm](#service-endpoint-expansion-algorithm). -5. Let **revocation index** be the integer value of the `revocationBitmapIndex` property contained in the `credentialStatus` of the **credential**. -6. Let **revoked** be the value of the bit at index **revocation index** in the **revocation bitmap**. -7. Return `true` if **revoked** is 1, `false` otherwise. - -## Test Vectors - -This section provides test vectors to validate implementations against. - -### Test Vector 1 - -The following data URL decodes to a bitmap of length 0 where no index is revoked: - -`"data:application/octet-stream;base64,ZUp5ek1tQUFBd0FES0FCcg=="` - -### Test Vector 2 - -The following data URL decodes to a bitmap of length 3 where indices `5`, `398`, and `67000` are revoked: - -`"data:application/octet-stream;base64,ZUp5ek1tQmdZR0lBQVVZZ1pHQ1FBR0laSUdabDZHUGN3UW9BRXVvQjlB"`. - -### Test Vector 3 - -The following data URL decodes to a bitmap of length 16384 where all indices are revoked: - -`"data:application/octet-stream;base64,ZUp6dHhERVJBQ0FNQkxESEFWS1lXZkN2Q3E0MmFESmtyMlNrM0ROckFLQ2RBQUFBQUFBQTMzbGhHZm9q"` - -## Rationale - -This section describes the rationale behind some of the design decisions of this specification. - -### Compression and maximum size - -Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/main/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. -The precise size of a serialized bitmap varies based on the number and distribution of revoked indices. When indices are revoked uniformly randomly, roughly 100,000 - 200,000 can be achieved in a DID Document with compression, and significantly more if consecutive indices are revoked. - -ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] was chosen for having a free and open source software licence and being one of the most widely used compression schemes, which enhances the accessibility of this specification. Some other assessed algorithms produced only marginally better compression ratios but had far fewer existing implementations across different programming languages. - -### Compressed Bitstring vs. Roaring Bitmap - -Because of its space efficiency, a roaring bitmap is preferred for representing a bitmap in-memory. To avoid the dependency on roaring bitmap, we considered using a compressed bitstring as the serialization format. However, serialization of such a bitstring was 2-3x slower compared to roaring's serialization format, which becomes an issue on resource-constrained devices (e.g. smartphones) or in web browsers. - -### Comparison to `RevocationList2020` and `StatusList2021` - -The [RevocationList2020 specification](https://w3c-ccg.github.io/vc-status-rl-2020/) and [StatusList2021 specification](https://w3c-ccg.github.io/vc-status-list-2021/) both describe a similar revocation mechanism using a verifiable credential that contains a bitmap, similar to the `RevocationBitmap2022` approach. The credential is hosted outside of the DID document and the verifier thus needs to fetch it from an external resource, likely one controlled by the issuer. This has privacy implications as the issuer can track where a fetch request for the credential came from and potentially infer who the credential was verified by and for what purpose. The issuer can also potentially infer which credential was checked. Because `RevocationBitmap2022` is embedded in the issuer's DID document, which can be obtained without the their knowledge, this approach does not suffer from these privacy shortcomings. See also the [privacy considerations](#privacy-considerations). - -A downside of embedding the revocation list in the DID document is that storage in a distributed ledger (DLT) is usually more expensive than other storage hosting solutions. The DLT might also impose message size limitations, capping the total number of revocations that can be done (see also [compression](#compression)). - -Another difference is that `RevocationList2020` specifies a minimum initial size of 131,072 for its bitstring, to mitigate the potential for correlating individuals when few credentials have been issued. `RevocationBitmap2022` uses a roaring bitmap instead of a bitstring, so the maximum size is not fixed (apart from the upper bound of an unsigned 32-bit integer). This means the bitmap cannot be used to correlate small populations without more information not present in the bitmap itself. However, both schemes still reveal publicly how many credentials have been revoked, which could be used to infer other information if more knowledge about how an issuer assigns credential revocation indexes is known. - -`StatusList2021` allows for explicitly stating the purpose of the list, currently either _revocation_ or _suspension_. This specification does not mandate that revoked credentials cannot be unrevoked, which means a `RevocationBitmap2022` can effectively also be used as a suspension list. - -### Privacy Considerations - -Because the revocation bitmap is embedded in the DID document, and thus available without contacting the issuer directly, the issuer cannot correlate how a holder uses their credential. - -An observer finding a service of type `RevocationBitmap2022` in a DID document can infer that this DID belongs to an issuer. However, DIDs of issuers tend to be publicly known, in contrast to DIDs of other entities, so this is unlikely to present an issue. External observers can monitor the frequency of revocations and potentially the total number of issued credentials, depending on how the issuer assigns credential indices (e.g. starting from 0 and incrementing the index for each issued credential). diff --git a/docs/build/identity.rs/0.6/docs/tutorials/migrate-stronghold.mdx b/docs/build/identity.rs/0.6/docs/tutorials/migrate-stronghold.mdx deleted file mode 100644 index 3b57852c24d..00000000000 --- a/docs/build/identity.rs/0.6/docs/tutorials/migrate-stronghold.mdx +++ /dev/null @@ -1,181 +0,0 @@ ---- -title: Migrate Stronghold -sidebar_label: Migrate Stronghold -description: Provides instructions on how to migrate Stronghold Snapshot files from v2 to v3 -image: /img/Identity_icon.png -keywords: - - tutorials ---- - -With the Rust 0.6.3 and Wasm 0.6.1 version of IOTA Identity, Stronghold was updated to [2.0](https://github.com/iotaledger/stronghold.rs/releases/tag/iota-stronghold-v2.0.0). The new Stronghold release, besides many security enhancements, introduces an updated Snapshot format and requires old Snapshots to be migrated to the new format. - -:::info - -Stronghold Snapshots v2 must be migrated to v3 before they can be used with Identity Rust 0.6.3 and Wasm 0.6.1. - -::: - -To migrate Stronghold Snapshot files from the v2 to the v3 format the following instructions using IOTA SDK for Rust or Nodejs can be utilized. - -:::danger - -After verifying that your new Stronghold Snapshot works as intended, make sure to securely delete the old Stronghold Snapshot and **all** of your backups, and replace them with backups of the migrated Stronghold Snapshot, if desired. - -::: - -## Rust - -To migrate a v2 Stronghold Snapshot from Identity 0.6.2 or earlier in Rust to a v3 Stronghold Snapshot that can be used with Identity 0.6.3 Rust or later, follow these steps: - -- Create a new crate with `cargo new --bin stronghold-migration && cd stronghold-migration`. -- Run `cargo add iota-sdk --features stronghold`. -- Run `cargo add anyhow`. -- Copy the code from [rust migration tool](#rust-migration-tool) into `main.rs`. -- The program takes 4 arguments, 2 of them required. - - Required: The path to the current stronghold snapshot. - - Required: The password to the current stronghold snapshot. - - Optional: The path where the migrated snapshot shall be written. If not given, the old snapshot will be overwritten. - - Optional: The password of the migrated snapshot. If not given, the current password will be used. -- Run `cargo run --release -- $CURRENT_PATH $CURRENT_PASSWORD $NEW_PATH $NEW_PASSWORD`. - -### Rust Migration Tool - -```rust -use std::{io::stdin, path::PathBuf, process::exit}; - -use iota_sdk::client::{stronghold::StrongholdAdapter, Password}; - -fn main() -> anyhow::Result<()> { - let mut args = std::env::args(); - // Skip file name. - args.next().expect("expected file name to be set"); - - let current_path: PathBuf = args - .next() - .expect("expected path to the current stronghold as the first argument") - .try_into()?; - - let current_password: Password = args - .next() - .expect("expected password of the current stronghold as the second argument") - .try_into()?; - - let new_path: Option = args.next().map(TryInto::try_into).transpose()?; - let new_password: Option = args.next().map(TryInto::try_into).transpose()?; - - if new_path.is_none() { - println!("WARNING: The current stronghold snapshot will be overwritten, since no new path was given. Enter `yes` to continue"); - let mut answer = String::new(); - stdin().read_line(&mut answer).unwrap(); - - if answer != "yes" { - println!("Operation aborted"); - exit(0); - } - } - - if new_password.is_none() { - println!("NOTE: The password of the new stronghold will be the same as the current one."); - } - - StrongholdAdapter::migrate_snapshot_v2_to_v3( - current_path, - current_password, - "identity.rs", - 100, - new_path, - new_password, - )?; - - println!("Migration successful."); - - Ok(()) -} -``` - -## Wasm - -To migrate a v2 Stronghold Snapshot from Identity 0.6.0 or earlier in Wasm to a v3 Stronghold Snapshot that can be used with Identity Wasm 0.6.1, follows these steps. Note that we're using the iota-sdk nodejs version for this process. - -- Create a new directory `mkdir stronghold-migration && cd stronghold-migration`. -- Run `npm init` and accept the defaults. -- Add these dependencies in `package.json`: - - `"@iota/sdk": "^1.0.3"` - - `"readline-sync": "^1.4.10"` -- Copy the code from [Wasm migration tool](#wasm-migration-tool) into a new file called `index.js`. -- The program takes 4 arguments, 2 of them required. - - Required: The path to the current stronghold snapshot. - - Required: The password to the current stronghold snapshot. - - Optional: The path where the migrated snapshot shall be written. If not given, the old snapshot will be overwritten. - - Optional: The password of the migrated snapshot. If not given, the current password will be used. -- Run `node index.js $CURRENT_PATH $CURRENT_PASSWORD $NEW_PATH $NEW_PASSWORD`. - -### Wasm Migration Tool - -```javascript -const { migrateStrongholdSnapshotV2ToV3 } = require('@iota/sdk'); -const readline = require('readline-sync'); - -async function migrate() { - const args = process.argv.slice(2); - let currentPath = args.at(0); - let currentPassword = args.at(1); - let newPath = args.at(2); - let newPassword = args.at(3); - - if (!currentPath) { - console.log( - 'expected path to the current stronghold as the first argument', - ); - process.exit(0); - } - - if (!currentPassword) { - console.log( - 'expected password of the current stronghold as the second argument', - ); - process.exit(0); - } - - currentPath = String(currentPath); - currentPassword = String(currentPassword); - - if (!newPath) { - const answer = readline.question( - 'WARNING: The current stronghold snapshot will be overwritten, since no new path was given. Enter `yes` to continue\n', - ); - - if (answer !== 'yes') { - console.log('Operation aborted'); - process.exit(0); - } - - newPath = currentPath; - } else { - newPath = String(newPath); - } - - if (!newPassword) { - console.log( - 'NOTE: The password of the new stronghold will be the same as the current one.', - ); - - newPassword = currentPassword; - } else { - newPassword = String(newPassword); - } - - migrateStrongholdSnapshotV2ToV3( - currentPath, - currentPassword, - 'identity.rs', - 100, - newPath, - newPassword, - ); - - console.log('Migration successful.'); -} - -migrate(); -``` diff --git a/docs/build/identity.rs/0.6/docs/tutorials/overview.mdx b/docs/build/identity.rs/0.6/docs/tutorials/overview.mdx deleted file mode 100644 index 5f734c7f3eb..00000000000 --- a/docs/build/identity.rs/0.6/docs/tutorials/overview.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Tutorials Overview -sidebar_label: Overview -description: Provide overview of the tutorials -image: /img/Identity_icon.png -keywords: - - tutorials ---- - -In this section you will find end-to-end examples using the library to achieve common use-cases. - -List of tutorials: - -- [Digitally Validate a Degree](./validate_university_degree.mdx): Use the Wasm bindings to digitally prove the existence and validity of a degree. diff --git a/docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx b/docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx deleted file mode 100644 index fa92ffe83f9..00000000000 --- a/docs/build/identity.rs/0.6/docs/tutorials/validate_university_degree.mdx +++ /dev/null @@ -1,224 +0,0 @@ ---- -description: In this tutorial, you will use the WASM binding of the IOTA Identity framework to digitally prove the existence and validity of a university degree. -image: /img/sequence_diagram.png -keywords: - - wasm - - decentralized identifiers - - did subject - - Verifiable credentials - - Verifiable Presentations - - validate - - degree - - university ---- - -# Digitally Validate a Degree - -In this tutorial, you will use the WASM binding of the IOTA Identity framework to digitally prove the existence and validity of a university degree. To follow along please clone [this repository](https://github.com/iotaledger/iota-identity-tutorial). - -The `src/` directory contains scripts that can be run separately by providing command line arguments. Make sure that the npm dependencies - which include -the wasm bindings for the IOTA Identity Framework - are installed by running: - -```bash -npm install -``` - -## Degree Validation - -Alice recently graduated from the University of Oslo with a Bachelor of Computer Science. Now, she wants to apply for a remote job at the IOTA Foundation and needs to digitally prove the existence and validity of her degree. What she needs is an immutable and verifiable credential, approved by both the University of Oslo and herself, before presenting it to her potential employer. - -## Roles - -As described in the [Digital Identities Solution](https://www.iota.org/solutions/digital-identity), IOTA Identity builds on the [W3C's proposed standards for a digital identity framework](https://www.w3.org/TR/did-core/) based on three roles: - -- **Holder**: Alice -- **Issuer**: University of Oslo -- **Verifier**: IOTA Foundation - -## Terms - -| Term | Definition | -| :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [Decentralized Identifier (DID)](https://www.w3.org/TR/did-core/#dfn-decentralized-identifiers) | A globally unique persistent identifier that does not require a centralized registration authority and is often generated and/or registered cryptographically. | -| [DID Subject](https://www.w3.org/TR/did-core/#dfn-did-subjects) | The entity identified by a DID and described by a DID document. Anything can be a DID subject: person, group, organization, physical thing, digital thing, logical thing, etc. | -| [DID Document](https://www.w3.org/TR/did-core/#dfn-did-documents) | A set of data describing the DID subject, including mechanisms, such as cryptographic public keys, that the DID subject or a DID delegate can use to authenticate itself and prove its association with the DID | -| [Verification Method](https://www.w3.org/TR/did-core/#dfn-verification-method) | A set of parameters that can be used together with a process to independently verify a proof. For example, a cryptographic public key can be used as a verification method for a digital signature; in such usage, it verifies that the signer possessed the associated cryptographic private key. | -| [Verifiable Credential](https://www.w3.org/TR/did-core/#dfn-verifiable-credentials) | A standard data model and representation format for cryptographically-verifiable digital credentials. It is signed by the issuer, to prove control over the Verifiable Credential with a nonce or timestamp. | -| Verifiable Presentation | A Verifiable Presentation is the format in which a (collection of) Verifiable Credential(s) gets shared. It is signed by the subject, to prove control over the Verifiable Credential with a nonce or timestamp. | -| [DID Resolution](https://www.w3.org/TR/did-core/#dfn-did-resolution) | The process that takes as its input a DID and a set of resolution options and returns a DID document in a conforming representation plus additional metadata. | - -## Sequence-Chart - -![banner](/img/sequence-diagram.png) - -## Storage - -In this tutorial, [Stronghold](https://github.com/iotaledger/stronghold.rs) will be used to securely store private keys. The Identity Framework already has [Stronghold bindings for Node.js](https://github.com/iotaledger/identity.rs/tree/dev/bindings/stronghold-nodejs). We will be using them in this tutorial. -For simplicity, each stronghold file will be responsible for storing only one DID. - -## Steps - -In this process, you will complete the different steps from the perspective of one of the mentioned roles above: - -### 1. **Holder**: Create a DID - -The first thing you will need to do in this tutorial is to create a DID (Decentralized Identifier) Document for Alice. -The script [createDid.ts](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/createDid.ts) can be used to create DIDs using the command: - -```bash -npm run start create-did -``` - -For Alice, a DID can be created using: - -```bash -npm run start create-did alice alice-password - -``` - -This will create a minimal DID document for alice, and publish it to the Tangle. A Stronghold file `alice.hodl` will be created under `/stronghold-files` which contains the Account's state and the private key of the main verification method of the DID. -`alice-password` will be used as a password for the stronghold storage. Obviously this password must be more secure in production applications. - -See [Creating a Decentralized Identity](../concepts/decentralized_identifiers/create.mdx) for more information about generating DIDs. - -### 2. **Issuer**: Create a DID - -Once you have created Alice's DID, you should do the same for the University of Oslo. - -```bash -npm run start create-did uni-of-oslo uni-password -``` - -with that `uni-of-oslo.hodl` will be created under `/stronhold-files`. - -### 3. **Issuer**: Add a Verification Method - -Since the university will need to issue a signed verifiable credential for Alice, a verification method should be added to the university's DID document. -Read more about adding verification methods in [update DID Documents](../concepts/decentralized_identifiers/update.mdx). - -To add a Verification Method the following command can be used: - -```bash -npm run start create-vm -``` - -This command will invoke [verificationMethods.ts](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/verificationMethods.ts). - -Note that `identity-name` is used to identify the Stronghold file location in `/stronghold-files` while `verification-fragment` is used to identify the Verification Method inside the DID Document. -To create a Verification Method for the issuer, use the following command: - -```bash -npm run start create-vm uni-of-oslo uni-password key-1 -``` - -### 4. **Holder**: Add a Verification Method - -Alice will need a verification method to sign verifiable presentations before sending them to third parties. Hence a verification method also needs to be added to her DID document. - -Similar to the issuer, the following command can be run to add a verification method to Alice's DID Document. - -```bash -npm run start create-vm alice alice-password key-1 -``` - -### 5: **Issuer**: Create Revocation list - -In order for the issuer to be able to revoke credentials in the future, a revocation list is needed. See [Verifiable Credential Revocation](../concepts/verifiable_credentials/revocation.mdx) for further details. -The following command can be used to create a revocation list: - -```bash -npm run start add-revocation-list -``` - -This will invoke [revocationBitmap.ts](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/revocationBitmap.ts). - -For the University of Oslo use: - -```bash -npm run start add-revocation-list uni-of-oslo uni-password rev-1 -``` - -Notice that `rev-1` is used to identity this revocation list inside the DID document. - -### 5 **Issuer**: Create Verifiable Credential - -University of Oslo can now issue a verifiable credential to Alice. The following command can be used to create a verifiable credential: - -```bash -npm run start create-vc -``` - -This will invoke [verifiableCredentials.ts](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/verifiableCredentials.ts). - -To create a verifiable credential for Alice, run the following command: - -```bash -npm run start create-vc uni-of-oslo uni-password alice key-1 rev-1 5 -``` - -Notice that `` needs to be replaced with Alice's DID. The reason we didn't use Alice's Stronghold file, is that the issuer doesn't have access to it in a real world scenario. -If you didn't note Alice's DID upon creating the DID, use `npm run start get-did alice alice-password` to log the DID saved in Alice's Stronghold file. - -This verifiable credential is given a revocation index of `5`, this will be used later when the verifiable credential will be revoked. \ -The command will execute the script in [verifiableCredentials.ts](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/verifiableCredentials.ts) which creates a verifiable credential using values provided as arguments -and hard-coded values to describe the issued degree. This credential will be tied to `rev-1` revocation list and then signed with `key-1` verification method.\ -Once the script execution finishes, the file `alice-credential.json` will be created in the `credentials/` directory. The file contains the credential in JSON format -and is usually sent back to Alice to store and enable her to prove her degree. - -### 6 **Holder**: Create Verifiable Presentation - -After Alice received the verifiable credential from the university, she applies for a job at the IOTA Foundation. The foundation requests a verifiable presentation -to be signed by alice that includes the challenge 'xyz123'. -The script [verifiablePresentation.ts](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/verifiablePresentation.ts) can be run with the command: - -```bash -npm run start create-vp -``` - -For Alice's case: - -```bash -npm run start create-vp alice alice-password alice-credential.json key-1 xyz123 -``` - -This will create a verifiable presentation of Alice's credential that includes the challenge and signed by Alice's `key-1` verification method. -The resulted presentation is saved in `presentations/alice-presentation.json`. - -### 7 **Verifier**: Verification - -Now alice sends the signed verifiable presentation to the IOTA Foundation. The foundation now has to verify if everything is correct and the credential is valid. - -The script [checkVerifiablePresentation](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/verifiablePresentation.ts) can be run with the command: - -```bash -npm run start verify-vp -``` - -So the foundation can run: - -```bash -npm run start verify-vp alice-presentation.json xyz123 - -``` - -Since everything was signed correctly, the verification should succeed. - -### 8 **Issuer**: Revocation - -Unfortunately the university found out, that Alice had cheated on her final exam. Therefore, the university wants to revoke the validity of Alice's credential. -Since the revocation list `rev-1` with revocation index `5` were used upon creating the verifiable credential, revocation is now possible by updating the revocation list. - -[revocation.ts](https://github.com/iotaledger/iota-identity-tutorial/tree/master/src/revocation.ts) can be run with the command: - -```bash -npm run start revoke-vc -``` - -To revoke Alice's Credential you can run: - -```bash -npm run start revoke-vc uni-of-oslo uni-password rev-1 5 -``` - -This will update the revocation list inside the issuer's DID Document and publish it to the tangle. Now if the IOTA Foundation tries to verify the credential again -e.g. by running `npm run start verify-vp alice-presentation.json xyz123`, This will throw an error since the verification now fails. diff --git a/docs/build/identity.rs/0.6/docs/workflow.mdx b/docs/build/identity.rs/0.6/docs/workflow.mdx deleted file mode 100644 index 1952b19f7ad..00000000000 --- a/docs/build/identity.rs/0.6/docs/workflow.mdx +++ /dev/null @@ -1,179 +0,0 @@ ---- -title: Identity.rs workflow -sidebar_label: Workflow -description: Learn about the software development process of the IOTA Identity repository. -image: /img/Identity_icon.png -keywords: - - Workflow - - Contribute - - GitHub - - explanation ---- - -# Identity Workflow - -In this article you will learn about the software development process for the IOTA Identity repository as well as key terms, functions, and the overall operability of the workflow components. - -## Issues - -Issues are opened when a certain task or problem is noted but cannot immediately be fixed. Issues may contain bug reports, requests, or larger topics. Please use the correct GitHub issue template for your issue type. Only IOTA Foundation members should use the task templates flagged for maintainers. You should make sure to [label](#issue-labels) the issue correctly. As a contributor, you may also add issues to a certain [project](https://github.com/iotaledger/identity.rs/projects/). - -## Git - -### Pull Requests - -New branches should be pushed to the GitHub repository as soon as possible, making them public to all contributors. In addition, a pull request (PR) should be opened in draft status, describing the goals and any requirements of the changes. To generate good [changelogs](#changelog), a PR title must be written in a way that is suitable as a changelog entry while the PR must be [labeled](#pr-labels) correctly. - -Any code written should frequently be committed and pushed back to the GitHub branch. This acts as both a back-up mechanism and provides transparency towards other contributors and the community. You should also pull from the origin branch of the PR regularly to prevent merge conflicts. - -Other contributors are encouraged to provide feedback on a PR during its development. A PR should be flagged as 'ready for review' once the PR has implemented all changes and no further commits are planned by the main contributors. The repository requires a review to be provided by at least one (other) developer in the team that works in the same language or has knowledge of the work before it can be merged. For larger PRs, the review of two maintainers is recommended. - -Once a PR is approved, the preferred method is "squash-and-merge" for non-epic branches to keep the destination branch clean and allow for many small commits while work is in-progress. Epic branches must instead be merged with the merge commits of included PRs intact, so the [changelog generator](#changelog) can detect included changes. Once merged in, the source branch may be deleted. - -### Branches - -IOTA Identity always has two permanent branches: `main` and `dev`. Both branches are protected and disallow direct commits; the only changes allowed are from pull requests approved and merged by maintainers. - -#### [Main](https://github.com/iotaledger/identity.rs/tree/main) (main) - -The `main` branch contains a stable version of the code that is released towards package managers such as `crates.io` and `npm`. This branch only accepts PRs that merge from `release` or `hotfix` branches. - -#### [Dev](https://github.com/iotaledger/identity.rs) (dev) - -The `dev` branch contains a frequently updated version of the code that is released towards package managers under a development flag. These releases may contain breaking changes without a strong notice towards developers using them. While the `dev` branch may get frequent updates, it may not contain unfinished features. Any large, multi-PR feature should be committed to a long-lived `epic` branch created specifically for that feature. - -### Work Branches - -These are branches that developers work on directly. Their names should be prefixed appropriately with one of the following categories. For example, a PR fixing a null pointer bug in the Wasm bindings might be created from a branch called `fix/client-non-null`. - -#### Feature (feat/, doc/, chore/, fix/) - -Singular PR contributions should create either a `feat`, `doc`, `chore`, or `fix` branch, depending on the type of changes. These may be branched from either the `dev` branch or an `epic` branch. If the number of lines of code are going to be relatively small and the work completed in a single PR, the branch should be created from `dev` and merged back into `dev` once completed. Otherwise, the branches should be created from their associated `epic` branch and be merged back into the same `epic` branch. - -- `feat` branches should contain changes to the code that expand or modify functionality. They should also include updates to the documentation and examples related to the feature, though `doc` branches may be used to catch up on documenting a feature. -- `doc` branches contain changes to code documentation or the wiki. These PRs should be kept relatively small to avoid burdening a reviewer with too many documentation updates at once. For example, during a documentation catch-up, we will have a branch or PR per documentation page. -- `chore` branches are short-lived branches that contain no significant features or functionality changes, but rather smaller fixes such as typos, code fixes, minor refactors, and CI changes. -- `fix` branches correct bugs such as compilation errors or where existing features do not behave as expected, generally without introducing any new functionality or breaking changes. - -We recommend integrating `dev` or `epic` regularly, depending on where the branch started, to reduce the possibility and potential size of merge conflicts. - -#### Epic (epic/) - -Long-lived `epic` branches should be created as soon as a feature is expected to require more than one PR. The `epic` branch should be branched from `dev` and should only accept merges that are related to the feature being developed. A PR should be opened as soon as the branch is created to publicly notify contributors about the development, the goals and requirements of the feature, and the existence of the branch. It is recommended you integrate `dev` often to reduce the possibility and potential size of merge conflicts. Epic branches must not be squash-merged, otherwise the [changelog generator](#changelog) will not detect its constituent PRs. - -### Semantic Versioning - -Semantic Versioning (SemVer) describes a methodology for versioning of software to convey meaning and guarantees through the version string. A typical version string looks like `2.3.1`, where `2` is called the major version, `3` the minor version and `1` the patch or bugfix version. - -The central idea is that every part of the version string conveys meaning. A major change introduces behavior that is incompatible with previous versions of the software, while a minor change adds backwards-compatible functionality and a patch simply fixes a problem. So just by looking at the version string, an implementer will understand the effort needed to integrate a new version. - -For more detailed information and an overview of advanced features, see [Semantic Versioning 2.0.0](https://semver.org/). Though this is not to be confused with [Sentimental Versioning](http://sentimentalversioning.org/). - -### Changelog - -A changelog is a file describing a software project for humans to grasp the type and content of changes from version to version. Changelogs are closely related to the versioning of software, since individual changes are grouped into versions that are, in our case, referenced by a [SemVer string](#semantic-versioning). We generally follow the recommendations from [keepachangelog](https://keepachangelog.com/en/1.0.0/). The changelog in this project is generated from the titles and [labels](#pr-labels) of [pull requests](#pull-requests). - -#### PR labels - -Labels are used to categorize changes in [pull requests](#pull-requests). Adding a label will include the labeled [PR](#pull-requests) title in the related section of the generated [changelog](#changelog). - -Changelogs are generated for the core Rust library and each binding separately. To attach a PR to a specific changelog, use the following labels: - -##### `Rust` - -This includes the PR in the core Rust library changelog. - -##### `Wasm` - -This includes the PR in the WASM bindings changelog. - -It is also necessary to add an appropriate label for the type of change in the PR. The following labels determine in which section a PR title will appear: - -##### Changed - -Maps to the major version of [Semantic Versioning](#semantic-versioning). -labels: `Breaking change` - -##### Added - -Maps to the minor version of [Semantic Versioning](#semantic-versioning). -labels: `Added` - -##### Patch - -Maps to the patch version of [Semantic Versioning](#semantic-versioning). -labels: `Patch` - -##### Deprecated - -Marks features that will be removed in the feature. No special version consideration should apply here, since the feature did not change yet. -labels: `Deprecated` - -##### Removed - -Marks features as being removed. Typically the features should have been deprecated in the previous version. This maps to the major version of [Semantic Versioning](#semantic-versioning). -labels: `Removed` - -##### Excluded tags - -Marks changes that should not be part of the changelog. This should only be used for documentation and rare exceptions. -labels: `Documentation`, `No changelog` - -Please note that a PR can only be listed in one section of a changelog. So attaching the labels `Rust` `Added` `Patch` to a PR, for example, is invalid because `Added` and `Patch` conflict. - -##### Release summary - -To attach a release summary to a version in the changelog, an issue with the label `release-summary` must be created. Create a GitHub milestone matching the version you want to describe and attach it to the issue. The issue can be closed immediately. The text of the issue will be included in the changelog as the release summary. - -### Issue Labels - -The following labels are used to categorize issues but do not have any effect on changelogs: `Request`, `Enhancement`, `Bug`, `Chore`, `Dependencies`, `Help wanted`, `Duplicate`, `Wontfix`. - -## Release - -With the release process, we can deliver versions of our software to the community. We use sensible automation where it helps to remove tedium. However, some steps that require active decision-making remain manual. - -The final list of changes from the [changelog](#changelog) informs the version of the release. If at least one change mapping to a major version is included, the major version needs to be incremented. In that case, the minor and patch versions are set to `0`. If there are no changes related to a major version, but changes related to a minor version are present, the minor version needs to be incremented while the patch version is set to `0`. Otherwise, only the patch version is incremented. Determining the version of the release is the responsibility of the person performing the release. - -The determined version of the release is used to create the [hotfix](#hotfix) or [release](#release) branch. For example, a major release from the previous version `v2.3.1` will create the `release/v3.0.0` branch. - -Notice the `v` in front of the version. We [tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging) all release in git in the form of `vMAJOR.MINOR.PATCH`. For bindings, we prefix the tag with the binding name, so a tag for Wasm would look like `wasm-v1.2.3`. Bindings and the core Rust library are versioned and released independently. - -Additionally, we may release `dev` versions separately for both bindings and the core Rust library. These releases are meant as a preview of upcoming versions. For example, if the current version is `1.2.3` with the tag `v1.2.3`, we may release `v1.3.0-dev.1` which is then superseded by the actual `1.3.0` release. - -You should follow these steps to create a release: - -1. Ensure all the changes you want to release are on the `dev` branch. -2. Select the appropriate GitHub Actions workflow, e.g. `Rust Create Release PR`. - 2.1. Decide if you want to create a `dev` or `main` release. - 2.2. Determine the next version string. - 2.3. Run the workflow. The workflow will create a PR from `dev` targeting `dev` with release related changes. -3. Review the PR. - 3.1. The PR will update the changelog, check that it has all expected entries in the appropriate sections and the determined version matches the changelog according to [SemVer](#semantic-versioning). - 3.2. The PR will update project version strings, ensure these are correct and match the expected version. - 3.3. Refer to [Troubleshooting](#troubleshooting) if anything is incorrect. -4. Merge the PR. - 4.1. On merging to `dev`, an automatic workflow is triggered that builds and publishes artifacts to the appropriate package manager (`crates.io` for Rust, `npm` for the WASM bindings), and creates a GitHub Release (only for `main` version releases of the core Rust library). -5. For `main` version releases, merge the `dev` branch into the `main` branch. - -### Troubleshooting - -#### The changelog entries have the wrong description in the release PR - -Update the titles of the relevant PRs, then re-run the workflow with the same parameters. The release PR will be updated with the new changelog. - -#### The changelog in the release PR is missing entries, has unrelated entries, or entries in the wrong section - -Fix the [labels](#pr-labels) on the relevant PRs, then re-run the workflow with the same parameters. The release PR will be updated with the new changelog. - -#### The release description in the release PR is missing or wrong - -Fix the issue description, milestone, and label according to the [release summaries guide](#release-summary) and re-run the workflow with the same parameters. The release PR will be updated with the new changelog. - -#### Features or code are missing from the release - -Merge the code into the `dev` branch, then re-run the workflow with the same parameters. The release PR will be updated with the changes. - -#### I want to abort the release for any reason - -Close the PR. You can reopen it later. // TODO: can I just re-run the workflow? Maybe that needs an "I want to resume an aborted release" section? diff --git a/docs/build/identity.rs/0.6/sidebars.js b/docs/build/identity.rs/0.6/sidebars.js deleted file mode 100644 index f124accc0ba..00000000000 --- a/docs/build/identity.rs/0.6/sidebars.js +++ /dev/null @@ -1,153 +0,0 @@ -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ - -module.exports = { - // By default, Docusaurus generates a sidebar from the docs folder structure - // tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], - - // But you can create a sidebar manually - - docs: [ - { - type: 'doc', - id: 'introduction', - label: 'Introduction', - }, - { - type: 'doc', - id: 'decentralized_identity', - label: 'Decentralized Identity', - }, - { - type: 'category', - label: 'Getting Started', - collapsed: false, - items: [ - 'getting_started/overview', - 'getting_started/install', - 'getting_started/create_and_publish', - ], - }, - { - type: 'category', - label: 'Concepts', - collapsed: false, - items: [ - { - 'Decentralized Identifiers (DID)': [ - 'concepts/decentralized_identifiers/overview', - 'concepts/decentralized_identifiers/create', - 'concepts/decentralized_identifiers/update', - 'concepts/decentralized_identifiers/resolve', - 'concepts/decentralized_identifiers/private_tangle', - ], - 'Verifiable Credentials': [ - 'concepts/verifiable_credentials/overview', - 'concepts/verifiable_credentials/create', - 'concepts/verifiable_credentials/revocation', - 'concepts/verifiable_credentials/verifiable_presentations', - ], - 'Advanced Concepts': [ - 'concepts/advanced/overview', - 'concepts/advanced/did_messages', - 'concepts/advanced/storage_interface', - ], - }, - ], - }, - { - type: 'category', - label: 'Programming Languages', - collapsed: true, - items: [ - 'libraries/overview', - { - type: 'category', - label: 'Rust', - collapsed: true, - items: ['libraries/rust/getting_started'], - }, - { - type: 'category', - label: 'WASM', - collapsed: true, - items: [ - 'libraries/wasm/getting_started', - 'libraries/wasm/api_reference', - ], - }, - ], - }, - { - type: 'category', - label: 'Tutorials', - items: [ - 'tutorials/overview', - 'tutorials/migrate-stronghold', - 'tutorials/validate_university_degree', - ], - }, - { - type: 'category', - label: 'Specifications', - collapsed: true, - items: [ - 'specs/overview', - 'specs/revocation_bitmap_2022', - { - type: 'category', - label: 'IOTA DID', - collapsed: true, - items: ['specs/did/overview', 'specs/did/iota_did_method_spec'], - }, - { - type: 'category', - label: 'IOTA DIDComm', - collapsed: true, - items: [ - 'specs/didcomm/overview', - { - type: 'category', - label: 'Protocols', - collapsed: true, - items: [ - 'specs/didcomm/protocols/connection', - 'specs/didcomm/protocols/authentication', - 'specs/didcomm/protocols/presentation', - 'specs/didcomm/protocols/issuance', - 'specs/didcomm/protocols/signing', - 'specs/didcomm/protocols/revocation', - 'specs/didcomm/protocols/revocation-options', - 'specs/didcomm/protocols/post', - 'specs/didcomm/protocols/termination', - ], - }, - { - type: 'category', - label: 'Resources', - collapsed: true, - items: [ - 'specs/didcomm/resources/credential-info', - 'specs/didcomm/resources/problem-reports', - ], - }, - 'specs/didcomm/CHANGELOG', - ], - }, - ], - }, - 'glossary', - 'contribute', - 'workflow', - 'contact', - 'faq', - ], -}; diff --git a/versionedConfig.js b/versionedConfig.js index cf2c3b8e3b5..f93acf0df39 100644 --- a/versionedConfig.js +++ b/versionedConfig.js @@ -76,14 +76,6 @@ exports.buildPluginsConfig = [ label: '1.0', badges: ['IOTA', 'Shimmer'], }, - { - label: '0.6', - badges: ['Deprecated'], - bannerPath: path.resolve( - __dirname, - 'banners/identity-06-deprecation-migration.mdx', - ), - }, ], }, { From 87b5b31d79eb9b840e3f26fa045f883982052ee8 Mon Sep 17 00:00:00 2001 From: Enrico Marconi Date: Fri, 26 Jan 2024 15:32:44 +0100 Subject: [PATCH 05/19] StatusList2021 --- .../verifiable-credentials/revocation.mdx | 91 ++++++++++++++++--- 1 file changed, 80 insertions(+), 11 deletions(-) diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx index 51efdcd78ee..8c837add8c3 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx @@ -17,20 +17,25 @@ import TabItem from '@theme/TabItem'; The [example](#example) below demonstrates two methods that an issuer can use to revoke a verifiable credential using the IOTA Identity Framework: -1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking to a -[revocation bitmap](#revocation-bitmap), -using the [`RevocationBitmap2022`](/identity.rs/references/specifications/revocation-bitmap-2022/). +1. By using the [`credentialStatus`](https://www.w3.org/TR/vc-data-model/#status) field in a credential and linking +to a [revocation method](#revocation-methods). 2. By [removing the verification method](#removing-the-verification-method) that signed the credential. This invalidates all credentials that were signed with that verification method. -## Revocation Bitmap - - -One of the ways for an issuer to control the status of its credentials is by using a revocation list. -At the most basic level, revocation information for all verifiable credentials issued by an issuer are expressed as -simple binary values. -The issuer keeps a list of all verifiable credentials it has issued in a bitmap. -Each verifiable credential is associated with a unique index in the list. +## Revocation methods +The IOTA Identity Framework supports two different revocation methods: `RevocationBitmap2022` and `StatusList2021`. +### Revocation Bitmap +[RevocationBitmap2022](/identity.rs/references/specifications/revocation-bitmap-2022/) is the default credential revocation method used in the IOTA Identity Framework. It allows +issuers to control whether a credential is _valid_ or _revoked_. To do so, a revocation list (represented +as a bitmap) is stored in the issuer's DID document. +When a credential is issued, a unique index from the issuer's revocation list +is chosen, linking the credential's status to the value of the list entry. To change the status of a credential, the issuer +simply updates the corresponding entry in its revocation list. + +With `RevocationBitmap2022` the `identity.rs` library completely handles the processes required to handle credentials revocation; +from creation and storage of the revocation list to its lookup. +This makes `RevocationBitmap2022` the preferred way for users to handle credential revocation, but it requires sufficient +funds to rent out the required on-tangle space. @@ -79,6 +84,70 @@ This bitmap written as a bitstring looks like this: `000001`. Here, the 5th bit is set, which means the credential with that index is revoked, while all other credentials aren't revoked. +### StatusList2021 +[StatusList2021](https://www.w3.org/TR/2023/WD-vc-status-list-20230427) offers similar functionalities but in a more flexible way. +The main difference is that `StatusList2021` is completely agnostic in regards to how the issuer's status list +is stored and fetched, as long as its location can be encoded through an URL. For instance, the status list +can be made available over HTTP (e.g. `http://example.com/credentials/status`) or through the +Interplanetary File System (e.g. `ipfs://QmXDWGdVBhbDoXXzKNMhJk5ejnZgxpMBVzW4EhQaHPD3Mi`). +This flexibility though requires the issuer to manually fetch and update its status list. + +Furthermore, credentials can be in any of these three different states: +- _valid_ +- _suspended_: the credential won't be temporarily accepted. This status can be reversed. +- _revoked_: the credential isn't valid anymore. This status **cannot** be reversed. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/8_status_list_2021.rs#L86-L90 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L72-L76 +``` + + + + +First, an issuer creates a credential that encodes a certain status list, specifying its purpose (either `revocation` or `suspension`) +and the location at which it will be available (`http://example.com/credentials/status` in this case). After creation, the issuer +must make the credential available at the chosen URL, so that verifiers may be able to fetch it. + + + + +```rust reference +https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/8_status_list_2021.rs#L173 +``` + + + + +```ts reference +https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L147 +``` + + + + +To set the status of a credential the issuer retrieves the status list credential and set the value of the chosen entry index. +This sets the `credentialStatus` of the revoked credential to something similar to the following snippet: + +```json +{ + "id": "https://example.com/credentials/status#94567", + "type": "StatusList2021Entry", + "statusPurpose": "revocation", + "statusListIndex": "94567", + "statusListCredential": "https://example.com/credentials/status" +} +``` + ## Removing the Verification Method A less efficient alternative is to remove the verification method that signed the credential from the DID Document of From 6e1ee5e0afbdf6fb5dc1696891cb235e221bd5c2 Mon Sep 17 00:00:00 2001 From: Enrico Marconi Date: Mon, 29 Jan 2024 14:54:54 +0100 Subject: [PATCH 06/19] StatusList2021 improvements --- .../verifiable-credentials/revocation.mdx | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx index 8c837add8c3..76318eca91e 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx @@ -85,17 +85,19 @@ Here, the 5th bit is set, which means the credential with that index is revoked, while all other credentials aren't revoked. ### StatusList2021 -[StatusList2021](https://www.w3.org/TR/2023/WD-vc-status-list-20230427) offers similar functionalities but in a more flexible way. +[StatusList2021](https://www.w3.org/TR/2023/WD-vc-status-list-20230427) offers similar functionalities to `RevocationBitmap2022` +but in a more flexible way. The main difference is that `StatusList2021` is completely agnostic in regards to how the issuer's status list is stored and fetched, as long as its location can be encoded through an URL. For instance, the status list can be made available over HTTP (e.g. `http://example.com/credentials/status`) or through the Interplanetary File System (e.g. `ipfs://QmXDWGdVBhbDoXXzKNMhJk5ejnZgxpMBVzW4EhQaHPD3Mi`). -This flexibility though requires the issuer to manually fetch and update its status list. -Furthermore, credentials can be in any of these three different states: -- _valid_ -- _suspended_: the credential won't be temporarily accepted. This status can be reversed. -- _revoked_: the credential isn't valid anymore. This status **cannot** be reversed. +This flexibility, although it requires the issuer to manually fetch and update its status list, allows for an arbitrary number of +entries in the status list, in contrast with `RevocationBitmap2022` where the lenght of the list is limited by the DLT's constraints. + +Furthermore, `StatusList2021` introduces a new credential state: _suspended_. Suspended credentials are credentials that will not be +accepted by a validator as _valid_, but that might become valid again in the future. Instead, _revoked_ credentials **cannot** ever +be valid again, as the _revoked_ state is irreversible. @@ -135,7 +137,7 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1 -To set the status of a credential the issuer retrieves the status list credential and set the value of the chosen entry index. +To set the status of a credential, the issuer retrieves the status list credential and set the value of the chosen entry index. This sets the `credentialStatus` of the revoked credential to something similar to the following snippet: ```json @@ -157,7 +159,7 @@ This means the VC can no longer be validated. However, this will also invalidate every VC signed with that verification method, meaning that the issuer will have to sign every VC with a different key to retain precise control over which credential is revoked. - +n From 37ce2f92c456842220dfbede4b3678566cc88fe2 Mon Sep 17 00:00:00 2001 From: Enrico Marconi <31142849+UMR1352@users.noreply.github.com> Date: Thu, 1 Feb 2024 13:40:31 +0100 Subject: [PATCH 07/19] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Eike Haß --- .../how-tos/verifiable-credentials/revocation.mdx | 6 +++--- .../verifiable-credentials/selective-disclosure.mdx | 12 ++++++------ 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx index 76318eca91e..9541160d6cd 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx @@ -86,10 +86,10 @@ while all other credentials aren't revoked. ### StatusList2021 [StatusList2021](https://www.w3.org/TR/2023/WD-vc-status-list-20230427) offers similar functionalities to `RevocationBitmap2022` -but in a more flexible way. +but in a more flexible and scalable way. The main difference is that `StatusList2021` is completely agnostic in regards to how the issuer's status list is stored and fetched, as long as its location can be encoded through an URL. For instance, the status list -can be made available over HTTP (e.g. `http://example.com/credentials/status`) or through the +can be made available over HTTP (e.g. `https://example.com/credentials/status`) or through the Interplanetary File System (e.g. `ipfs://QmXDWGdVBhbDoXXzKNMhJk5ejnZgxpMBVzW4EhQaHPD3Mi`). This flexibility, although it requires the issuer to manually fetch and update its status list, allows for an arbitrary number of @@ -117,7 +117,7 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1 First, an issuer creates a credential that encodes a certain status list, specifying its purpose (either `revocation` or `suspension`) -and the location at which it will be available (`http://example.com/credentials/status` in this case). After creation, the issuer +and the location at which it will be available (`https://example.com/credentials/status` in this case). After creation, the issuer must make the credential available at the chosen URL, so that verifiers may be able to fetch it. diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx index ed9c7189348..127b55d1187 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx @@ -15,15 +15,15 @@ import TabItem from '@theme/TabItem'; # Selective Disclosure (SD-JWT) -Holders of verifiable credentials may prefer not to disclose all the information contained within it to the verifier. Instead, they may opt to share only a specific subset of the properties included in the VC. The identity library implements the [IETF Specifications](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html) which outlines a mechanism to enable the selective disclosure of individual properties within the JSON object of JWT claims. +Holders of verifiable credentials may prefer not to disclose all the information contained within the credential to a verifier. Instead, they may opt to only share a specific subset of the properties included in the VC. The identity library implements the [IETF Specifications](https://www.ietf.org/archive/id/draft-ietf-oauth-selective-disclosure-jwt-07.html) which outlines a mechanism to enable the selective disclosure of individual properties within the JSON object of JWT claims. ## Concept #### Issuance ✍️ -During the issuance process, the issuer replaces a subset of the JWT claims with digests of their salted values and signs the JWT. Next, the signed JWT alongside with the plain text disclosures and the salt used the for digest creation are sent to the holder. +During the issuance process, the issuer replaces a subset of the fields contained in a credential with digests of their salted values and creates a signed JWT. Next, JWT alongside the plain text disclosures and the salt used the for digest creation are sent to the holder. #### Presentation 📃 -At this stage, the holder has the flexibility to selectively choose which values to disclose to the verifier. The chosen values are sent in plain text with the JWT that contains the digests to the verifier. +At this stage, the holder has the flexibility to selectively choose which fields to disclose to the verifier. The chosen disclosures are sent in plain text together with the JWT that contains the digests to the verifier. :::note Only values replaced by digests through the issuer can be selectively disclosed. The holder **can not** conceal values provided in plain text in the JWT claims. @@ -95,15 +95,15 @@ The issuer makes the values of "locality", "postal_code", "street_address" selec ``` :::note -The digests are included in the `_sd` property in `address`. This allows both keys and values to be concealed. +The digests are contained in the `_sd` property in `address`. This allows both keys and values to be concealed. ::: -For further details, see the [Example](#full-example-code) below and the [sd-jwt-payload crate](https://github.com/iotaledger/sd-jwt-payload). +For further details, see the [example](#full-example-code) below and the [sd-jwt-payload crate](https://github.com/iotaledger/sd-jwt-payload). ## Key Binding JWT -When a verifier receives an SD-JWT, it could be important to verify if the identity of the presenter matches the holder of the Credential. For that a Key binding JWT can be used, in which the holder can verify the possession of the private key that corresponds with his public key. +When a verifier receives an SD-JWT, it may be desirable to verify that the identity of the presenter matches the holder of the Credential. For that purpose a Key Binding JWT can be used, in which the holder can proof the possession of the private key that corresponds with his public key. ## Full Example Code From f664f3e0bead30d0c5592da4c2ac2c674f6b7342 Mon Sep 17 00:00:00 2001 From: Enrico Marconi Date: Thu, 1 Feb 2024 15:32:32 +0100 Subject: [PATCH 08/19] revocation suggestions --- .../verifiable-credentials/revocation.mdx | 34 ++++++++++++------- 1 file changed, 22 insertions(+), 12 deletions(-) diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx index 9541160d6cd..90f0aa9d10d 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx @@ -37,6 +37,13 @@ from creation and storage of the revocation list to its lookup. This makes `RevocationBitmap2022` the preferred way for users to handle credential revocation, but it requires sufficient funds to rent out the required on-tangle space. +:::note + +The size of the revocation list is limited by DLT's size constraints. With the assumption of only one such revocation list +per issuer's DID document, one may expect to be able to handle roughly around 50k entries. + +::: + @@ -120,6 +127,20 @@ First, an issuer creates a credential that encodes a certain status list, specif and the location at which it will be available (`https://example.com/credentials/status` in this case). After creation, the issuer must make the credential available at the chosen URL, so that verifiers may be able to fetch it. +Upon issueing a credential, in order to revoke it or suspend it later on, the issuer sets the `credentialStatus` field, linking +to an entry in its status list. The snippet below shows what `credentialStatus` would look like when linking to the previously created +status list credential. + +```json +{ + "id": "https://example.com/credentials/status#94567", + "type": "StatusList2021Entry", + "statusPurpose": "revocation", + "statusListIndex": "94567", + "statusListCredential": "https://example.com/credentials/status" +} +``` + @@ -137,18 +158,7 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1 -To set the status of a credential, the issuer retrieves the status list credential and set the value of the chosen entry index. -This sets the `credentialStatus` of the revoked credential to something similar to the following snippet: - -```json -{ - "id": "https://example.com/credentials/status#94567", - "type": "StatusList2021Entry", - "statusPurpose": "revocation", - "statusListIndex": "94567", - "statusListCredential": "https://example.com/credentials/status" -} -``` +To set the status of a credential, the issuer retrieves the status list credential and sets the value of the chosen entry index. ## Removing the Verification Method From 2b9d1d4a6bbb150fc78e9975028ded66cfcc36c7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eike=20Ha=C3=9F?= Date: Fri, 2 Feb 2024 13:29:29 +0100 Subject: [PATCH 09/19] pin examples to correct version --- .yarnrc | 5 +++++ .../1.0/docs/getting-started/rust.mdx | 2 +- .../1.0/docs/getting-started/wasm.mdx | 2 +- .../decentralized-identifiers/create.mdx | 20 +++++++++---------- .../decentralized-identifiers/delete.mdx | 8 ++++---- .../decentralized-identifiers/resolve.mdx | 4 ++-- .../decentralized-identifiers/update.mdx | 4 ++-- .../domain-linkage/create-and-verify.mdx | 4 ++-- .../1.0/docs/how-tos/key-storage.mdx | 8 ++++---- .../how-tos/verifiable-credentials/create.mdx | 12 +++++------ .../verifiable-credentials/revocation.mdx | 12 +++++------ .../create-and-validate.mdx | 4 ++-- .../specifications/iota-did-method-spec.mdx | 6 +++--- .../specifications/revocation-bitmap-2022.mdx | 2 +- .../1.1/docs/getting-started/rust.mdx | 2 +- .../1.1/docs/getting-started/wasm.mdx | 2 +- .../decentralized-identifiers/create.mdx | 20 +++++++++---------- .../decentralized-identifiers/delete.mdx | 8 ++++---- .../decentralized-identifiers/resolve.mdx | 4 ++-- .../decentralized-identifiers/update.mdx | 4 ++-- .../domain-linkage/create-and-verify.mdx | 4 ++-- .../1.1/docs/how-tos/key-storage.mdx | 8 ++++---- .../how-tos/verifiable-credentials/create.mdx | 12 +++++------ .../verifiable-credentials/revocation.mdx | 20 +++++++++---------- .../selective-disclosure.mdx | 4 ++-- .../create-and-validate.mdx | 4 ++-- .../specifications/iota-did-method-spec.mdx | 6 +++--- .../specifications/revocation-bitmap-2022.mdx | 2 +- 28 files changed, 99 insertions(+), 94 deletions(-) create mode 100644 .yarnrc diff --git a/.yarnrc b/.yarnrc new file mode 100644 index 00000000000..5ef1bed4b9a --- /dev/null +++ b/.yarnrc @@ -0,0 +1,5 @@ +# THIS IS AN AUTOGENERATED FILE. DO NOT EDIT THIS FILE DIRECTLY. +# yarn lockfile v1 + + +yarn-path ".yarn/releases/yarn-1.22.19.cjs" diff --git a/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx b/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx index 431e991c5f0..7bde26fd342 100644 --- a/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx +++ b/docs/build/identity.rs/1.0/docs/getting-started/rust.mdx @@ -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: diff --git a/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx b/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx index 22978fca285..037de1f21fb 100644 --- a/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx +++ b/docs/build/identity.rs/1.0/docs/getting-started/wasm.mdx @@ -338,4 +338,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) diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx index 5c3f0bccc25..306e841fa0b 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/create.mdx @@ -45,14 +45,14 @@ you will need an output with actual Shimmer or IOTA funds to create a new Alias ```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 ``` ```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 ``` @@ -77,14 +77,14 @@ the DID inside the document. ```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 ``` ```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 ``` @@ -107,14 +107,14 @@ However, they must be unlocked in order perform a state or governance transition ```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 ``` ```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 ``` @@ -139,14 +139,14 @@ the DID Document is stored on the ledger and can be [resolved](resolve.mdx) usin ```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 ``` ```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 ``` @@ -159,14 +159,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0 ```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 ``` ```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 ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx index 465cafff339..46567c9a5ca 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/delete.mdx @@ -46,14 +46,14 @@ and optionally reclaiming the storage deposit. ```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 ``` ```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 ``` @@ -92,14 +92,14 @@ The following example demonstrates a governor destroys an IOTA Identity and send ```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 ``` ```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 ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx index 87814227334..609fe4a759e 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/resolve.mdx @@ -167,14 +167,14 @@ and [credentials](./../../explanations/verifiable-credentials.mdx). ```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 ``` ```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 ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx index c888221877b..70b966cfc99 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/decentralized-identifiers/update.mdx @@ -520,14 +520,14 @@ Publish the updated DID Document inside the Alias Output taking into account the ```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 ``` ```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 ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx b/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx index c01de0c4c23..b9147c92cff 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/domain-linkage/create-and-verify.mdx @@ -165,14 +165,14 @@ You can learn more ```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 ``` ```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 ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx b/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx index 1e1fdb28673..50afe04ef92 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/key-storage.mdx @@ -119,14 +119,14 @@ This section shows the Rust and TypeScript `Memstore` implementations. ```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 ``` ```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 ``` @@ -138,14 +138,14 @@ https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_sto ```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 ``` ```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 ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx index d38cad99f94..34b09e5cee7 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/create.mdx @@ -83,14 +83,14 @@ In this example, the issuer signs a `UniversityDegreeCredential` with Alice's na ```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 ``` ```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 ``` @@ -104,14 +104,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0 ```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 ``` ```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 ``` @@ -127,14 +127,14 @@ allowing Alice to take control of it and share it with anyone. ```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 ``` ```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 ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx index 51efdcd78ee..25bd0cfb647 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-credentials/revocation.mdx @@ -36,14 +36,14 @@ Each verifiable credential is associated with a unique index in the list. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L167 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/7_revoke_vc.rs#L167 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 ``` @@ -94,14 +94,14 @@ precise control over which credential is revoked. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L197-L204 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/7_revoke_vc.rs#L197-L204 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 ``` @@ -115,14 +115,14 @@ The following code exemplifies how you can revoke a [Verifiable Credential (VC)] ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/7_revoke_vc.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx index b1a8cdc47b3..ba5dc8874cb 100644 --- a/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx +++ b/docs/build/identity.rs/1.0/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -102,14 +102,14 @@ and finally validate it with various options. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/6_create_vp.rs +https://github.com/iotaledger/identity.rs/blob/v1.0.0/examples/0_basic/6_create_vp.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/6_create_vp.ts +https://github.com/iotaledger/identity.rs/blob/v1.0.0/bindings/wasm/examples/src/0_basic/6_create_vp.ts ``` diff --git a/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx b/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx index 87787af978b..731572cfa72 100644 --- a/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx +++ b/docs/build/identity.rs/1.0/docs/references/specifications/iota-did-method-spec.mdx @@ -22,7 +22,7 @@ The IOTA DID Method Specification describes a method of implementing the [Decent ## Data Types & Subschema Notation -Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/main/tips/TIP-0021/tip-0021.md). +Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0021/tip-0021.md). ## Introduction @@ -36,13 +36,13 @@ Data stored in an output and covered by the storage deposit will be stored in _a ### Alias Output -The [Alias Output](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: +The [Alias Output](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: - **Amount**: the amount of IOTA coins held by the output. - **Alias ID**: 32 byte array, a unique identifier of the alias, which is the BLAKE2b-256 hash of the Output ID that created it. - **State Index**: A counter that must increase by 1 every time the alias is state transitioned. -- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/main/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. +- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. - **Unlock Conditions**: - State Controller Address Unlock Condition - Governor Address Unlock Condition diff --git a/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx b/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx index e44aa2c11b0..8b90194d32d 100644 --- a/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx +++ b/docs/build/identity.rs/1.0/docs/references/specifications/revocation-bitmap-2022.mdx @@ -175,7 +175,7 @@ This section describes the rationale behind some of the design decisions of this ### Compression and maximum size -Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/main/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. +Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/v1.0.0/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. The precise size of a serialized bitmap varies based on the number and distribution of revoked indices. When indices are revoked uniformly randomly, roughly 100,000 - 200,000 can be achieved in a DID Document with compression, and significantly more if consecutive indices are revoked. ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] was chosen for having a free and open source software licence and being one of the most widely used compression schemes, which enhances the accessibility of this specification. Some other assessed algorithms produced only marginally better compression ratios but had far fewer existing implementations across different programming languages. diff --git a/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx b/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx index 431e991c5f0..883fc036fd2 100644 --- a/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx +++ b/docs/build/identity.rs/1.1/docs/getting-started/rust.mdx @@ -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.1.0/examples), you should: 1. Clone the repository: diff --git a/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx index 22978fca285..c0f95904988 100644 --- a/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx +++ b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx @@ -338,4 +338,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.1.0/bindings/wasm/examples/README.md) diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx index 5c3f0bccc25..7f4b1d0c380 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/create.mdx @@ -45,14 +45,14 @@ you will need an output with actual Shimmer or IOTA funds to create a new Alias ```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.1.0/examples/0_basic/0_create_did.rs#L52 ``` ```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.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L40-L51 ``` @@ -77,14 +77,14 @@ the DID inside the document. ```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.1.0/examples/0_basic/0_create_did.rs#L59-L71 ``` ```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.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L55C44-L65 ``` @@ -107,14 +107,14 @@ However, they must be unlocked in order perform a state or governance transition ```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.1.0/examples/0_basic/0_create_did.rs#L75 ``` ```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.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L70 ``` @@ -139,14 +139,14 @@ the DID Document is stored on the ledger and can be [resolved](resolve.mdx) usin ```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.1.0/examples/0_basic/0_create_did.rs#L78 ``` ```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.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts#L74 ``` @@ -159,14 +159,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0 ```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.1.0/examples/0_basic/0_create_did.rs ``` ```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.1.0/bindings/wasm/examples/src/0_basic/0_create_did.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx index 465cafff339..9d7e18a446c 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/delete.mdx @@ -46,14 +46,14 @@ and optionally reclaiming the storage deposit. ```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.1.0/examples/0_basic/3_deactivate_did.rs ``` ```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.1.0/bindings/wasm/examples/src/0_basic/3_deactivate_did.ts ``` @@ -92,14 +92,14 @@ The following example demonstrates a governor destroys an IOTA Identity and send ```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.1.0/examples/0_basic/4_delete_did.rs ``` ```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.1.0/bindings/wasm/examples/src/0_basic/4_delete_did.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx index 87814227334..c4d0077ee5a 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/resolve.mdx @@ -167,14 +167,14 @@ and [credentials](./../../explanations/verifiable-credentials.mdx). ```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.1.0/examples/1_advanced/5_custom_resolution.rs ``` ```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.1.0/bindings/wasm/examples/src/1_advanced/4_custom_resolution.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx index c888221877b..d374ad3998d 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/decentralized-identifiers/update.mdx @@ -520,14 +520,14 @@ Publish the updated DID Document inside the Alias Output taking into account the ```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.1.0/examples/0_basic/1_update_did.rs ``` ```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.1.0/bindings/wasm/examples/src/0_basic/1_update_did.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx b/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx index c01de0c4c23..874bc10192f 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/domain-linkage/create-and-verify.mdx @@ -165,14 +165,14 @@ You can learn more ```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.1.0/examples/1_advanced/6_domain_linkage.rs ``` ```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.1.0/bindings/wasm/examples/src/1_advanced/5_domain_linkage.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx b/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx index 1e1fdb28673..fe02f54f18b 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/key-storage.mdx @@ -119,14 +119,14 @@ This section shows the Rust and TypeScript `Memstore` implementations. ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/lib/jwk_storage.ts +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/lib/jwk_storage.ts ``` ```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.1.0/identity_storage/src/key_storage/memstore.rs ``` @@ -138,14 +138,14 @@ https://github.com/iotaledger/identity.rs/blob/main/identity_storage/src/key_sto ```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.1.0/bindings/wasm/lib/key_id_storage.ts ``` ```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.1.0/identity_storage/src/key_id_storage/memstore.rs ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx index d38cad99f94..8da5ee2df72 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/create.mdx @@ -83,14 +83,14 @@ In this example, the issuer signs a `UniversityDegreeCredential` with Alice's na ```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.1.0/examples/0_basic/5_create_vc.rs#L67-L98 ``` ```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.1.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L51-L74 ``` @@ -104,14 +104,14 @@ https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0 ```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.1.0/examples/0_basic/5_create_vc.rs#L105-L113 ``` ```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.1.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts#L83-L88 ``` @@ -127,14 +127,14 @@ allowing Alice to take control of it and share it with anyone. ```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.1.0/examples/0_basic/5_create_vc.rs ``` ```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.1.0/bindings/wasm/examples/src/0_basic/5_create_vc.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx index 90f0aa9d10d..2ac5290d5bf 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/revocation.mdx @@ -48,14 +48,14 @@ per issuer's DID document, one may expect to be able to handle roughly around 50 ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L167 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/7_revoke_vc.rs#L167 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L156 ``` @@ -110,14 +110,14 @@ be valid again, as the _revoked_ state is irreversible. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/8_status_list_2021.rs#L86-L90 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/8_status_list_2021.rs#L86-L90 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L72-L76 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L72-L76 ``` @@ -145,14 +145,14 @@ status list credential. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/8_status_list_2021.rs#L173 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/8_status_list_2021.rs#L173 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L147 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/7_status_list_2021.ts#L147 ``` @@ -175,14 +175,14 @@ n ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs#L197-L204 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/7_revoke_vc.rs#L197-L204 ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts#L192C1-L195 ``` @@ -196,14 +196,14 @@ The following code exemplifies how you can revoke a [Verifiable Credential (VC)] ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/7_revoke_vc.rs +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/7_revoke_vc.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/7_revoke_vc.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx index 127b55d1187..745ad4b2746 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-credentials/selective-disclosure.mdx @@ -112,14 +112,14 @@ When a verifier receives an SD-JWT, it may be desirable to verify that the ident ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/1_advanced/7_sd_jwt.rs +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/1_advanced/7_sd_jwt.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/1_advanced/6_sd_jwt.ts +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/1_advanced/6_sd_jwt.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx index b1a8cdc47b3..09a33b7d83c 100644 --- a/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx +++ b/docs/build/identity.rs/1.1/docs/how-tos/verifiable-presentations/create-and-validate.mdx @@ -102,14 +102,14 @@ and finally validate it with various options. ```rust reference -https://github.com/iotaledger/identity.rs/blob/main/examples/0_basic/6_create_vp.rs +https://github.com/iotaledger/identity.rs/blob/v1.1.0/examples/0_basic/6_create_vp.rs ``` ```ts reference -https://github.com/iotaledger/identity.rs/blob/main/bindings/wasm/examples/src/0_basic/6_create_vp.ts +https://github.com/iotaledger/identity.rs/blob/v1.1.0/bindings/wasm/examples/src/0_basic/6_create_vp.ts ``` diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx index 87787af978b..684653b175f 100644 --- a/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx +++ b/docs/build/identity.rs/1.1/docs/references/specifications/iota-did-method-spec.mdx @@ -22,7 +22,7 @@ The IOTA DID Method Specification describes a method of implementing the [Decent ## Data Types & Subschema Notation -Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/main/tips/TIP-0021/tip-0021.md). +Data types and subschemas used throughout this TIP are defined in [TIP-21](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0021/tip-0021.md). ## Introduction @@ -36,13 +36,13 @@ Data stored in an output and covered by the storage deposit will be stored in _a ### Alias Output -The [Alias Output](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/main/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: +The [Alias Output](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0018/tip-0018.md#alias-output) is a specific implementation of the [UTXO state machine](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0018/tip-0018.md#chain-constraint-in-utxo). Some of its relevant properties are: - **Amount**: the amount of IOTA coins held by the output. - **Alias ID**: 32 byte array, a unique identifier of the alias, which is the BLAKE2b-256 hash of the Output ID that created it. - **State Index**: A counter that must increase by 1 every time the alias is state transitioned. -- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/main/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. +- **State Metadata**: Dynamically sized array of arbitrary bytes with a length up to `Max Metadata Length`, as defined in [TIP-22](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0022/tip-0022.md). Can only be changed by the state controller. - **Unlock Conditions**: - State Controller Address Unlock Condition - Governor Address Unlock Condition diff --git a/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx b/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx index e44aa2c11b0..f559ce5f12a 100644 --- a/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx +++ b/docs/build/identity.rs/1.1/docs/references/specifications/revocation-bitmap-2022.mdx @@ -175,7 +175,7 @@ This section describes the rationale behind some of the design decisions of this ### Compression and maximum size -Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/main/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. +Considering that messages published to the Tangle cannot exceed [32 KiB](https://github.com/iotaledger/tips/blob/v1.1.0/tips/TIP-0006/tip-0006.md#message-validation) in size, and that larger messages have increased requirements, the use of compression was assessed. The precise size of a serialized bitmap varies based on the number and distribution of revoked indices. When indices are revoked uniformly randomly, roughly 100,000 - 200,000 can be achieved in a DID Document with compression, and significantly more if consecutive indices are revoked. ZLIB [[RFC 1950](https://datatracker.ietf.org/doc/html/rfc1950)] was chosen for having a free and open source software licence and being one of the most widely used compression schemes, which enhances the accessibility of this specification. Some other assessed algorithms produced only marginally better compression ratios but had far fewer existing implementations across different programming languages. From 6850badd0240ca0a331d07efd453236547e41b23 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Eike=20Ha=C3=9F?= Date: Fri, 2 Feb 2024 14:14:20 +0100 Subject: [PATCH 10/19] reference sandbox --- docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx | 4 ++-- .../docs/how-tos/decentralized-identifiers/create.mdx | 9 ++++----- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx index c0f95904988..7ad0ddfe868 100644 --- a/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx +++ b/docs/build/identity.rs/1.1/docs/getting-started/wasm.mdx @@ -84,8 +84,8 @@ npm run build:web ## NodeJS Usage -The following code creates a new IOTA DID Document suitable for publishing to a locally running private network. -See the [instructions](https://github.com/iotaledger/hornet/tree/develop/private_tangle) on running your own private network. +The following code creates a new IOTA DID Document suitable for publishing to a local test network, like the +[IOTA Sandbox](/iota-sandbox/welcome/).