verifiable-conditions

Status of This Document

This document is not a W3C Standard nor is it on the W3C Standards Track. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

Comments regarding this document are welcome. Please file issues and PRs directly on Github.

Editors:

TODO: turn into a Re-spec page and host https://respec.org/docs

Introduction

VerifiableCondition is a new type of verification method for DID Documents. It can be used to express complex conditions and additional meta data about verification methods. It can be used to combine verification methods together to form conjugated conditions such as logical operations &&, thresholds, weighted thresholds, relationships and a delegation to external verification methods.

This new type has been created from discussions during the Decentralized Identity Foundation’s ID working group sessions. The need for this type has arisen from the current creation of the EOSIO DID method by Gimly. The type is designed to cover several other important use cases requiring similar conditional logic.

Prior work:

Goals

Create a new verification method type that can:

Use Cases

Support for account and key models of the following protocols:

The VerifiableCondition Type

A illistrative object of VerifiableCondition type showing the potential properties of the object. Note that not all these properties would exist for this to be a valid object.

{
    "id": "did:example:123#owner",
    "controller": "did:example:123",
    "type": "VerifiableCondition2021",
    "threshold": 0,
    "conditionAnd": [],
    "conditionOr": [],
    "conditionThreshold": [],
    "conditionWeightedThreshold": [],
    "conditionDelegated": "",
    "relationshipParent": [],
    "relationshipChild": [],
    "relationshipSibling": []
}

A verificationMethod which has a “VerifiableCondition2021” type is a verifiable condition. A verifiable condition type MUST specify one and only one fulfillment condition (And, Or, Threshold, WeightedThreshold and Delegated) by have a corresponding object property for that condition. A verifiable condition MAY specify one or more relationships (Parent, Child, Sibling) by having a corresponding object property for that relationship.

The And, Or, Threshold and WeightedThreshold fulfillment condition MUST be either an array of verification methods, or relative DID URL to a verification method on the same DID Document. These verification methods can be of any type, including VerifiableCondition types, creating a recursive structure able to express infinite conditional logic complexity about the cryptographic material required.

The Delegated fulfillment condition MUST be a DID URL string.

The relationships MUST be an array of DID URLs.

Example

The following DID shows a verificationMethod #1 which requires proofs to match the condition of AND( OR( #1-1-1, #1-1-2), #1-2) to be fulfilled. Note different key types are used as well.

{
     "@context": [
         "https://www.w3.org/ns/did/v1",
         "https://example.com/did/verifiable-conditions/v1"
     ],
    "id": "did:example:123",
    "type": "VerifiableCondition2021",
    "verificationMethod": [
        {
            "id": "did:example:123#1",
            "controller": "did:example:123",
            "type": "VerifiableCondition2021",
            "conditionAnd": [{
                "id": "did:example:123#1-1",
                "controller": "did:example:123",
                "type": "VerifiableCondition2021",
                "conditionOr": [{
                    "id": "did:example:123#1-1-1",
                    "controller": "did:example:123",
                    "type": "EcdsaSecp256k1VerificationKey2019",
                    "publicKeyBase58": "5JBxKqYKzzoHrzeqwp6zXk8wZU3Ah94ChWAinSj1fYmyJvJS5rT"
                }, {
                    "id": "did:example:123#1-1-2",
                    "controller": "did:example:123",
                    "type": "Ed25519VerificationKey2018",
                    "publicKeyBase58": "PZ8Tyr4Nx8MHsRAGMpZmZ6TWY63dXWSCzamP7YTHkZc78MJgqWsAy"
                }]
            }, {
                "id": "did:example:123#1-2",
                "controller": "did:example:123",
                "type": "Ed25519VerificationKey2018",
                "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV"
            }]
        }
    ]
}

This is an example of a verifiable presentation that fulfills the above DID’s verificationMethod #1 with two signatures #1-1-1 and #1-2.

{
    "@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": "http://example.edu/credentials/1872",
        "type": ["VerifiableCredential", "AlumniCredential"],
        "issuer": "https://example.edu/issuers/565049",
        "issuanceDate": "2010-01-01T19:73:24Z",
        "credentialSubject": {
            "id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
            "alumniOf": {
                "id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
                "name": [{
                "value": "Example University",
                "lang": "en"
                }, {
                "value": "Exemple d'Université",
                "lang": "fr"
                }]
            }
        },
        "proof": {
            "type": "RsaSignature2018",
            "created": "2017-06-18T21:19:10Z",
            "proofPurpose": "assertionMethod",
            "verificationMethod": "https://example.edu/issuers/keys/1",
            "jws": "eyJhbGciOiJSUzI1NiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19..TCYt5X
                sITJX1CxPCT8yAV-TVkIEq_PbChOMqsLfRoPsnsgw5WEuts01mq-pQy7UJiN5mgRxD-WUc
                X16dUEMGlv50aqzpqh4Qktb3rk-BuQy72IFLOqV0G_zS245-kronKb78cPN25DGlcTwLtj
                PAYuNzVBAh4vGHSrQyHUdBBPM"
            }
    }],
    "proof":  [{
            "type": "JsonWebSignature2020",
            "created": "2020-02-15T17:13:18Z",
            "verificationMethod": "did:example:123#1",
            "proofPurpose": "assertionMethod",
            "jws": "eyJiNjQiOmZhbHNlLCJjcml0IjpbImI2NCJdLCJhbGciOiJFZERTQSJ9.Y0KqovWCPAeeFhkJxfQ22pbVl43Z7UI-X-1JX32CA9MkFHkmNprcNj9Da4Q4QOl0cY3obF8cdDRdnKr0IwNrAw"
        }, {
            "type": "JsonWebSignature2020",
            "created": "2020-02-15T17:13:18Z",
            "verificationMethod": "did:example:123#1",
            "proofPurpose": "assertionMethod",
            "jws": "53Fm3mYG9ZJWwRDgyTt9aRDfpsZCGWycS8VChbvdF7PBgHo6MjKCB5k8.
                    6mV1meQzLKDraHdMzneojsw8eqRYcf7EvXVPC1X2ZRgGHdBHmUhYM4CVt6v4uV4JZ51PWxnB31bM9VvVjaVWu"
        }
    ]
}

Subtypes of VerifiableCondition2021

And

{
    "id": "did:example:123#1",
    "controller": "did:example:123",
    "type": "VerifiableCondition2021",
    "conditionAnd": []
}

Fulfilled if all of the verificationMethods provided are fulfilled.

Note: this subtype can be expressed through a Threshold subtype by setting the “threshold” property to the the number of verificationMethods.

Or

{
    "id": "did:example:123#1",
    "controller": "did:example:123",
    "type": "VerifiableCondition2021",
    "conditionOr": []
}

Fulfilled if any one of the verificationMethods provided are fulfilled.

Note: this subtype can be expressed through a Threshold subtype by setting the “threshold” property to 1.

Threshold

{
    "id": "did:example:123#4",
    "controller": "did:example:123",
    "type": "VerifiableCondition2021",
    "threshold": 3,
    "conditionThreshold": [],
}

Fulfilled if the number of verificationMethods that are fulfilled are greater than or equal to the “threshold” property.

Note: this subtype can be expressed through a WeightedThreshold subtype by setting all the “weight” properties to 1.

WeightedThreshold

{
    "id": "did:example:123#5",
    "controller": "did:example:123",
    "type": "VerifiableCondition2021",
    "threshold": 3,
    "conditionWeightedThreshold": [{
        "condition": [],
        "weight": 2
    }, {
        "condition": [],
        "weight": 2
    }, {
        "condition": [],
        "weight": 1
    }]
}

Fulfilled if the sum of the weights of the verificationMethods that are fulfilled are greater than or equal to the “threshold” property.

Delegated

{
    "id": "did:example:123#10",
    "controller": "did:example:123",
    "type": "VerifiableCondition2021",
    "conditionDelegated": ""
}

Fulfilled if the verificationMethod found by dereferencing the DID URL “conditionDelegated” is fulfilled. The dereferenced DID document MUST contain a verificationMethod found using the DID URL. The dereferenced DID document MUST NOT contain multiple verificationMethods found using the DID URL.

Relationships

{
    "id": "did:example:123#10",
    "controller": "did:example:123",
    "type": "VerifiableCondition2021",
    "relationshipParent": [],
    "relationshipChild": [],
    "relationshipSibling": [],
}

Has no fulfillment requirements.

If one of these properties exist, it MUST be an array of DID URLs.

This verificationMethod type is useful to express information for wallet mangement and for proofs.

For Hierarchical Deterministic (HD) Wallets or other types of heirachial wallets such as EOSIO, the relationship between different keys in the wallets is required so that the wallets may correctly update its key hierarchy. For example, a parent key is required to update child keys on an EOSIO blockchain.

Such relationship information is useful for wallet management, but can also be used in proofs. For example, an application may require that any approved is for fulfilled if it contains a child key of “did:example:123#1”.