We apologize that our current implementation does not yet support the Stardust Upgrade from IOTA. As such, you cannot issue or verify credentials associated via a did:iota. Please refer to our roadmap for more information on when our products will be updated to include this latest changes.
The following section outlines the planned integration of the IOTA identity framework with the walt.id SSI Kit and gives insight on the architecture of the integration and the required changes that need to be applied to the SSI Kit to establish smooth interoperability with the IOTA ecosystem.
The IOTA identity framework, much like the walt.id SSI Kit, is based on open standards for decentralized identity, such as the W3C specifications for verifiable credentials and decentralized identifiers (DIDs) and provides creation, management and registration of DIDs on the IOTA DLT technology (tangle), as well, as issuance, signing and validation of verifiable credentials.
In addition to the open standards for decentralized identity, the IOTA identity frameword implements a custom DID method, which needs to be supported by the walt.id SSI Kit to ensure compatibility.
Thanks to the use of W3C standards for DID documents and verifiable credentials, the SSI Kit is mostly compatible with the IOTA identity framework, with regards to DID documents and issuance/validation of verifiable credentials. Also the key type Ed25519, used in the IOTA framework is already supported by the SSI Kit.
The following aspects have been identified, which require implementation changes and/or integration work in the SSI Kit:
IOTA DID method: Creation, management and registration of DIDs on the IOTA tangle
Key management: Integrate SSI Kit key management seamlessly, such that keys managed by the SSI Kit (or a supported key store implementation) can be leveraged in the context of the IOTA framework.
Signature type: To ensure compatibility of issued credentials with both the SSI Kit and the IOTA framework, the LD-signature type JcsEd25519Signature2020 needs to be supported in the SSI Kit.
Public key format: The public key, stored in the verification methods of the IOTA DID documents, is formatted in multibase encoding, for which support in the SSI Kit needs to be provided.
The following subsections give more details on the planned integration work.
The following chart outlines the overall architecture of the integration between the walt.id SSI Kit and the IOTA framework:
In order to overcome the native-to-managed-code gap between the IOTA identity framework libraries, written in Rust, and the SSI Kit in Kotlin/JVM, a wrapper library is implemented in Rust, which includes the IOTA libraries as a dependency and exposes a plain C-compatible application binary interface (ABI).
The wrapper library can be loaded in Kotlin/JVM using the JNR-FFI abstracted foreign function layer library. The advantage compared to JNI (Java Native Interface) is that no Java-specific interface code needs to be written in the native wrapper library, such that the same library could be used from various other programming and scripting languages, that support loading of native dynamic libraries.
This approach also facilitates portability of the wrapper library to all operating systems and platforms supported by the Rust compiler and the IOTA framework library.
For DID creation and management, the wrapper library implements an interface method, called by the IotaService component in the SSI Kit.
The public and private keys for creating the DID, should be managed by the SSI Kit and its key store abstraction layer, with support for various key store implementations (see also Key management below).
The wrapper library makes use of the AccountBuilder of the identity_iota::account module to create and register a DID on the IOTA ledger. After creation the library updates the DID document to include the various verification method relationships, such that issuance (assertionMethod) and presentation (authentication) of verifiable credentials is permitted using the new DID.
The created DID document is returned to the SSI Kit, where it can be parsed and stored for further use.
In order to be able to make full use of the SSI Kit together with the IOTA framework, it is preferred to share the key store between both worlds.
The SSI Kit provides a key store abstraction layer, that has support for various key store implementations, including an embedded key store and cryptography library, as well as cloud-based HSM stores, such as Azure key vault and the walt.id Storage Kit, a general-purpose distributed encrypted data store.
In order to leverage the SSI Kit key store abstraction with the IOTA identity framework integration, we plan to implement a key store mediator component in the Rust wrapper library, which exposes the IOTA storage interface on the one hand, and, on the other hand, communicates the signing or encryption/decryption requests to the SSI Kit via a native-to-managed callback function. This key store mediator can be passed to the AccountBuilder as to storage interface to use for DID creation. The SSI Kit can then fulfill the cryptographic requests using the configured key store implementation and hand back the result to the wrapper library and IOTA framework internals.
The IOTA identity framework makes use of the JcsEd25519Signature2020 LD-signature type for signing and validation of verifiable credentials.
Thus, to be compatible with the credentials issued by the IOTA framework,the SSI Kit needs to be extended to support this type of signature.
To make the SSI Kit compatible with the DID documents created by the IOTA identity framework, it is required to support Multibase encoding of the verification material in the verification method objects, according to the latest DID specification, as for the time being, an older version of said specification is implemented, using Base58 encoding.
Given the support of multibase encoded verification material, the DID documents should be fully compatible with the SSI Kit.
We apologize that our current implementation does not yet support the Stardust Upgrade from IOTA. As such, you cannot issue or verify credentials associated via a did:iota. Please refer to our roadmap for more information on when our products will be updated to include this latest changes.
Authors: Severin Stampler (walt.id) December 2022
Login-with-IOTA is defined as a profile of the OpenID Connect for Verifiable Presentations specification [OIDC4VP], which defines the protocol for authorization using SSI, based on top of OAuth 2.0 [RFC6749] and introduces protocol extensions for the presentation of claims via Verifiable Credentials [VC_DATA_MODEL]. In this document we will describe the specifics of using the OIDC4VP protocol in the scope of Login-with-IOTA to ensure compatibility with the IOTA identity framework [IOTA_IDENTITY].
The IOTA identity framework [IOTA_IDENTITY] defines a custom DID method [IOTA_DID], based on the public key of the user account. The key material used is an EdDSA/Ed25519 [RFC8032] key pair.
| DID method | Key algorithm |
|---|---|
To ensure compatibility with the IOTA identity framework [IOTA_IDENTITY], the issuers and holders of verifiable credentials should use a did:iota for issuance and as credential subject.
The credentials used by the IOTA identity framework [IOTA_IDENTITY] are in line with the W3C specification for Verifiable Credentials [VC_DATA_MODEL]. Every type of credential, that is compatible with the W3C specification, should in theory be supported.
Proofs for the credentials are created in the linked data format, ldp_vc or ldp_vp, as described by the W3C data integrity specification [VC_DATA_INTEGRITY], using [JSON-LD] as the credential format and the JCS Ed25519 Signature 2020 [JcsEd25519Signature2020] signature type.
| Format | Signature type |
|---|---|
The [OIDC4VP] specification is based on top of OAuth 2.0 [RFC6749], which enables implementers to also build on top of OpenID Connect [OIDC] and the Self-issued OpenId Provider specification [SIOPv2].
This Login-with-IOTA profile of the [OIDC4VP] specification supports only W3C Verifiable Credentials [VC_DATA_MODEL].
Like described by [OIDC4VP], verifiable presentations can be requested by adding the presentation_definition parameter to the authorization request. The presentation is returned in the vp_token response parameter.
Both, same-device and cross-device flows are supported by this profile. For cross-device scenarios [OIDC4VP] introduces a new response mode post, to support verifier initiated verification.
The parameters for a Login-with-IOTA authorization request, are a subset of the parameters defined by the [OIDC4VP] specification:
response_type: REQUIRED. this parameter is defined in [RFC6749]. The possible values are determined by the response type registry established by [RFC6749]. This specification introduces the response type vp_token. This response type asks the Authorization Server (AS) to return only a VP Token in the Authorization Response.
presentation_definition: CONDITIONAL. A string containing a presentation_definition JSON object as defined in Section 4 of [DIF.PresentationExchange].
presentation_definition_uri: CONDITIONAL. A string containing a URL pointing to a resource where a presentation_definition JSON object as defined in Section 4 of [DIF.PresentationExchange] can be retrieved .
nonce: REQUIRED. This parameter follows the definition given in [OIDC]. It is used to securely bind the verifiable presentation(s) provided by the AS to the particular transaction.
state: OPTIONAL. State provided by the authorization client, that is passed through to the response.
A request MUST contain either a presentation_definition or a presentation_definition_uri. Those two ways to request credential presentations are mutually exclusive. The wallet MUST refuse any request violating this requirement.
The presentation_definition parameter must contain a JSON representation of a Presentation Definition object, according to the DIF Presentation Exchange specification [DIF.PresentationExchange].
Alternatively the request could contain the presentation_definition_uri parameter, containing a URL to a presentation definition object.
The following example shows a presentation definition object, requesting the presentation of a VerifiableId credential:
This is an example authorization request:
The response parameters depend on the response_type defined in the authorization request. Possible response parameters include:
id_token: The ID token as defined by section 2 of the [OIDC] core specification.
presentation_submission: The presentation submission object, as defined in [DIF.PresentationExchange], which links the input descriptors of the presentation definition in the request to the corresponding presentation(s) in the vp_token response.
state: Optional state parameter passed through from the authorization request.
Depending of the response_type given in the authorization request, the response should contain the following parameters, like described in section 6.1 of [OIDC4VP]:
If only vp_token is used as the response_type, the VP Token is provided in the authorization response.
If id_token is used as the response_type alongside vp_token, the VP Token is provided in the OpenID Connect authentication response along with the ID Token.
In all other cases, if vp_token is not used, but presentation_definition parameter is present, the VP Token is provided in the Token Response.
Any combination of vp_token with a response_type other than id_token is undefined.
The vp_token response parameter contains the verifiable presentation or array of verifiable presentations, matching the input descriptors of the presentation definition, specified in the authorization request.
The only supported format of the verifiable presentation in this specification is the [ldp_vp] / [JSON-LD] format. The JSON data can be either a single presentation object or an array of JSON objects and must be URL encoded.
The presentation submission object contains the correlations of the input descriptors, specified in the presentation definition of the authorization request, with the verifiable presentations in the VP token of the response. The format of the presentation submission objects is defined in section 6 of [DIF.PresentationExchange].
This is an example response for the respones_type=vp_token request parameter, with the presentation_submission and vp_token response parameters:
An example vp_token, containing a presentation with a VerifiableId credential:
An example presentation_submission object:
For creating compliant error responses, please refer to section 6.3 of [OIDC4VP].
For the same device flow, the verifier or relying party, links directly to the authorization endpoint of the wallet, passing the request parameters, as specified in the Authorization request section.
The response_mode should be set to form_post. After getting the user consent, the wallet will generate the response parameters, as specified in the Authorization response section, and performs a HTTP FORM POST action to the redirect_uri specified in the authorization request. The relying party can now verify the authorization response and redirect the user to the protected web page.
For the cross-device flow, the verifier or relying party initiates an internally cached authorization session and displays a QR code containing the authorization request URI with the request parameters, as specified in the Authorization request section.
The response_mode should be set to post. The wallet scans the QR code and parses the authorization request. After getting the user consent, the wallet will generate the response parameters, as specified in the Authorization response section, and posts the response to the redirect_uri specified in the authorization request, via the HTTP POST method. The relying party can now verify the authorization response and update the state of the internally cached authorization session. Depending on the concrete implementation (for example by polling for the session state), the relying party UI can now be refreshed and redirected to the protected page.
Terbu, O., Lodderstedt, T., Yasuda, K., Lemmon, A., Looker, T., "OpenID for Verifiable Presentations", September 2022, https://openid.net/specs/openid-4-verifiable-presentations-1_0.html
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, https://www.rfc-editor.org/info/rfc6749
Sporny, M., Longley, D., Chadwick, D., "Verifiable Credentials Data Model v1.1", March 2022, https://www.w3.org/TR/vc-data-model/
IOTA Foundation, "IOTA Identity Framework Guide", https://wiki.iota.org/identity.rs/introduction/
Millenaar, J., IOTA Foundation, "IOTA DID Method Specification", https://wiki.iota.org/identity.rs/specs/did/iota_did_method_spec/
Josefsson, S.; Liusvaara, I. (January 2017). Edwards-Curve Digital Signature Algorithm (EdDSA). IRTF. doi:10.17487/RFC8032. ISSN 2070-1721. RFC 8032. https://datatracker.ietf.org/doc/html/rfc8032
Longley, D., Sporny, M., "Verifiable Credential Data Integrity 1.0", https://w3c.github.io/vc-data-integrity/
Sporny, M., Longley, D., Kellog, G., Lanthaler, M., Champin, P., Lindström, N., "JSON-LD 1.1", https://www.w3.org/TR/json-ld11/
Cohen, G., Steele, O, Decentralized Identity Foundation, "JCS Ed25519 Signature 2020", https://identity.foundation/JcsEd25519Signature2020/
N. Sakimura, J. Bradley, M. Jones, B. de Medeiros, C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 1", November 8, 2014, https://openid.net/specs/openid-connect-core-1_0.html
K. Yasuda, M. Jones, T. Lodderstedt, "Self-Issued OpenID Provider v2", September 2022, https://openid.bitbucket.io/connect/openid-connect-self-issued-v2-1_0.html
Buchner, D., Zundel, B., Riedel, M., and K. H. Duffy, "Presentation Exchange 2.0.0", , https://identity.foundation/presentation-exchange/spec/v2.0.0/.