Ariadne Identity 1.0.0

Summary

This document describes a protocol to claim, prove and verify online accounts and link them together to form online identities. The method is designed to be lightweight, decentralized, secure, and rely on well-known and commonly-used technologies and standards.

Table of Contents

• Summary
• Table of Contents
• Related specifications
• Conventions
• Definitions
• Identity claim
• Identity proof
• Claim container
• Service provider
• Identity claim verification
• Online identity verification
• Considerations
  • Verification client considerations
  • Claim verification considerations

Related specifications

The service providers compatible with this specification are defined in the Ariadne Identity Service Providers 1.0.0 specification.

The claim containers compatible with this specification are defined in the Ariadne Identity Claim Containers 1.0.0 specification.

Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119.

This specification uses the Augmented Backus-Naur Form (ABNF) notation of RFC2234.

Definitions

Online identity — a collection of linked identity claims.

Identity claim — a reference to an online account that one person holds and would like to prove their hold over to another person.

Identity proof — a reference to a claim container.

Claim container — a digital document that is publicly read, privately written and identified by a unique identifier. This could be a cryptographic keypair or even a text document hosted on a domain.

Online account — any form of digital property that is accessible through a network but is privately held or controlled. This is usually an online account (for example, on a social network), a domain name, or even a cryptographic keypair.

Bidirectional linking — the process of linking from a claim container to an online account using an identity claim, and linking from that online account back to the claim container using an identity proof.

Verification client — software used to verify identity claims.

Identity claim

An identity claim MUST be formatted as a URI and MUST point to a valid online account. An identity claim MUST be formatted as either a direct URI or a data URI.

A direct URI claim MUST reference an online account with the least amount of information needed to deduce the location of the account and perform its verification.

Formatting of direct URIs vary between service providers. They could be the URL to a profile on an online platform or a URI with a scheme unique to a service provider or technology.

Examples of direct URIs:

# Account on social network
https://social.example/@username

# Account on social network which needs a post for claim verification
https://social.example/@username/post-123

# Account on code forge which needs a repo for claim verification
https://forge.example/@username/proof-repo

# Domain name
dns:domain.example

A data URI claim MUST be formatted as follows:

claim-data-uri = "data:application/vnd.ariadne.claim+json;service=" service-id "," data

Where service-id is the unique service provider identifier and data is a JSON object with properties specific to the service provider. These properties are defined per service provider in the Ariadne Identity Service Providers 1.0.0 specification

The data URI claim has the benefit of explicitly stating the targeted service provider, making the claim verification more efficient and more reliable.

Examples of data URIs:

data:application/vnd.ariadne.claim+json;service=example,{"domain":"domain.example","username":"username"}
data:application/vnd.ariadne.claim+json;service=dns,{"domain"="domain.example"}

A data URI SHOULD use base64-encoded data:

data:application/vnd.ariadne.claim+json;service=example;base64,eyJkb21haW4iOiJkb21haW4uZXhhbXBsZSIsInVzZXJuYW1lIjoidXNlcm5hbWUifQ==
# is the same as
# data:application/vnd.ariadne.claim+json;service=example,{"domain":"domain.example","username":"username"}

Identity proof

A non-hashed identity proof MUST be formatted as a URI and MUST be a valid reference to an existing claim container. Each claim container format defines its own URI to be used as identity proof, which are defined in the Ariadne Identity Claim Containers 1.0.0 specification

The non-hashed identity proof URI MUST contain the minimum amount of information needed to deduce the location of the claim container document.

Example of identity proof:

openpgp4fpr:1234567890123456789012345678901234567890

To obfuscate the identifier of the claim container, identity proofs MAY be hashed. To hash identity proofs, they MUST first be converted to lowercase strings. The entire resulting string is then used as input of the hashing function.

One of the following hashing functions MUST be used:

1. argon2.
2. bcrypt.

Examples of hashed identity proofs:

# argon2 hash of openpgp4fpr:1234567890123456789012345678901234567890
$argon2id$v=19$m=64,t=512,p=2$H+lSpQhS3ASQ7HkGLmSA1Q$d/9t1yDjkcnw778Pv6f+dw

# bcrypt hash of openpgp4fpr:1234567890123456789012345678901234567890
$2a$11$F8jQnOfQ1.QO5FiEJkQ.zOA8IrFuEXlP1niPBEkvcPSXKshmWOrHO

Claim container

A claim container is a digital document that:

1. MUST be publicly readable.
2. MUST be privately writable.
3. MUST have a unique identifier.

Verification clients SHOULD support the claim containers described in the Ariadne Identity Claim Containers 1.0.0 specification.

Service provider

A service provider is a publicly accessible service or technology that can host arbitrary data on behalf of individuals or organisations, and exposes this data in a way that it can be used for identity claim verification. This usually means that the data can be obtained encoded as JSON by performing an HTTP request at a public endpoint.

Verification clients SHOULD support the service providers described in the Ariadne Identity Service Providers 1.0.0 specification.

Identity claim verification

To verify an identity claim:

1. Parse the claim URI.
2. If the claim URI is a direct URI, perform steps 4-7 for all potential service providers.
3. If the claim URI is a data URI, perform steps 4-7 only for the service provider specified in the URI.
4. Deduce the possible locations of the identity proof from the claim URI.
5. Fetch the data at the locations from step 4.
6. Search the data from step 5 for the identity proof (direct or hashed).
7. If the identity proof is found in the data, mark the claim as verified.

To perform steps 4-7, verification clients SHOULD use the information provided by the Ariadne Identity Service Providers 1.0.0.

Online identity verification

To verify an online identity:

1. Fetch the claim container using its identifier.
2. Parse the claim container and read the identity claims.
3. For each identity claim, perform the steps from Identity claim verification.

Considerations

Verification client considerations

Verification clients handle information that could be used to identify individuals. Verification clients MUST, to the best of their ability, handle the data they are handed with caution.

Verification clients:

1. SHOULD NOT store data for an unnecessarily long time.
2. SHOULD NOT log unnecessarily or keep logs for a long time.
3. SHOULD avoid making unnecessary network requests.
4. SHOULD NOT communicate their activity with third parties without consent.

Claim verification considerations

To avoid unnecessary and wasteful usage of network bandwidth, as well as limiting network requests containing identifiers to servers with potentially malicious logging practices, verification clients SHOULD, to the best of their ability, filter the list of potential service providers to be tried during the Identity claim verification.

If a claim URI is a data URI, then the verification client SHOULD only try the service provider specified in the data URI.

If a claim URI is a direct URI, there is rarely absolute certainty on which service provider matches the claim URI. Potential methods to filter the list of service providers include:

Search the claim URI for clues: some service providers use a unique domain name. If the claim URI uses that domain name, the verification client SHOULD only try that one service provider.

Perform a public API call unique to a service provider: some service providers expose an API endpoint to obtain the version number of the software running on the service. If the API endpoint's response is not satisfactory, then the verification client SHOULD skip the service provider. This is also helpful when trying to distinguish between forks of a codebase.

The Ariadne Identity Service Providers 1.0.0 specification has filtering criteria for service providers when available.