Purpose of this document

This specification defines a universal DID method for Legal Entities.

Glossary

Name	Meaning
EBSI	European Blockchain Services Infrastructure
DID	Decentralised Identifier

Method Syntax

DID schema and method name

EBSI defines the following schema for Legal Entities: did:ebsi [network]:[method-specific-identifier]

Name	Meaning
Network	A unique identifier for EBSI-compliant DID Registries. This is fully omitted for the EBSI blockchain.
Method Specific Identifier	A unique identifier for Legal Entities.

Generation of a method-specific identifier

A Method Specific Identifier (MSI) is a unique and case-sensitive component of the DID. The uniqueness of the DID identifier for Legal Entities is enforced through the DID Registry.

Structure

An EBSI MSI is always encoded in the multibase:base58btc format, meaning the identifier always starts with the character "z". The rest of the identifier consists of a byte array of the subject, with a single byte prefix defining the MSI version as a number.

An EBSI MSI can be presented as: multibase.base58btc([version byte], [..subject identifier bytes])

Type	Version Byte	Subject Identifier Byte	Total Size
Legal Entities	1	Random 16 bytes	17 bytes

Method operation

Authorisation

No authorisation is required to read existing DID documents and their accreditations. The APIs for the EBSI DID Registry are defined here. Write operations are restricted by the EBSI Authorisation service and by the CapabilityInvocation key. The onboarding process exclusively employs the EBSI Authorisation service and adheres to the procedures defined in the Issuer onboarding and accreditation guidelines.

DID creation

To create a DID, it is encouraged to use any JWS-supported cryptographic algorithm, with ES256 being the minimum mandatory requirement.

JsonWebKey2020 is the recommended DID document verification method. However, other methods can also be used, provided they are converted into the JWK format.

info

A DID document's verification method may only contain a single key once, and the key name cannot be edited.

DIDs must be created locally and stored in the EBSI DID Registry. Details of the full process can be found in the Register a did document guidelines.

tip

JWK Thumbprint is the preferred key name for consistency.

DID resolution

DID documents can be resolved by querying the DID Registry, whose authenticity is achieved through a mandatory HTTPS connection. DID documents are resolved by default at "now", but for Verifiable Credential (VC) validation purposes, they must be resolved at the time of the VC issuance. The DID document timeline can be controlled with the valid-at query parameter. The full API can be found on the page Get a DID document.

DID document lifecycle

All updates or deactivations of a DID must be performed through the DID Registry. Clearing out the DID document's capabilityInvocation keys or controller property will make the DID immutable. A DID document cannot be removed, but the keys can be revoked or set to expire at a certain date, which will effectively deactivate the DID.

info

Revoking keys will affect the VCs issued after the notAfter time.

DID authority

The controller property defines which DIDs are the controller for the DID document. By default, the DID should control its own DID document, but this role can also be delegated to other DIDs. A DID controller has full authority over the DID, allowing it to register accreditations.

The capabilityInvocation property defines which keys can be used in smart contract transactions.

The DIDs with the modifier's capabilityInvocation key are defined by the target DID document's controller property. The modifier's DID must be included in the target's controller property.

The authentication property is used to verify the signatures of Verifiable Presentations and ID Tokens.

The assertionMethod property is used to verify the signatures of VCs.

Authority example

Usually, the controller of a DID document is the DID itself. In situations where additional security and control are required, the DID authority can be used in place of the DID.

Enterprises can opt-in to have an acyclic-directed graph of DIDs representing their organisations or security boundaries. The Root DID controllers, of which there can be many, may contain multiple keys (operational and cold storage) and have control over any graph of Child DIDs. Control of Child DIDs can be forfeited and given to Root DID(s), thereby allowing the Child DID to only authenticate and/or issue verifiable credentials. This approach enables high-security key rolling updates while optimising the signing process for the particular type of credential. The risk associated with leaking private keys is reduced, as all private keys can be scoped to meet the necessary security requirements.

In the following setup, the Root DID can control itself and the Child DID, whereas the Child DID is restricted and can only issue VCs. The Root DID also contains an operational key and a cold storage key for recovery purposes.

DID	Manage EBSI platform	Issue Verifiable Credentials	Authenticate
Root (did:ebsi:zvHWX359A3CvfJnCYaAiAde)	Sign EBSI transactions as self and on behalf of Child.	Can issue VCs as self.	Can authenticate as self.
Child (did:ebsi:zxA9t4Z2uorEVnx9njWUYvR)	No capability	Can issue VCs as self	No capability

DID record

---- Root DID document ----
{
  "@context": "https://w3id.org/did/v1",
  "id": "did:ebsi:zvHWX359A3CvfJnCYaAiAde",
  "controller": [
    "did:ebsi:zvHWX359A3CvfJnCYaAiAde"
  ],
  "verificationMethod": [
    {
      "id": "did:ebsi:zvHWX359A3CvfJnCYaAiAde#F0r5Oyt_lahvvz6MWlYs3mcYNKZiiQdUfqv8tshHN9w",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zvHWX359A3CvfJnCYaAiAde",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "ZYE6uX3XvQ9rLc6s0eeo2YiOM2VfwrEZOZXzTOthcHE",
        "y": "k-t1bfe-MmmXWQ0QaxK3uJMYlMNkJHYGUSLpxP9RQak",
        "alg": "ES256"
      }
    },
    {
      "id": "did:ebsi:zvHWX359A3CvfJnCYaAiAde#HnlK0wApxuRLLuCl1d1N3eL0_1ZvnNa3oBsTpBL1FNU",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zvHWX359A3CvfJnCYaAiAde",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "x": "EKpnPiX6IIs6vw2M03pWNuI2OORfLgotH0-gcZC0jv8",
        "y": "_1swhdgVvwnCHzuIVhG4cXXM4bV1c9I6OOTU_6xxDfo",
        "alg": "ES256K"
      }
    },
    {
      "id": "did:ebsi:zvHWX359A3CvfJnCYaAiAde#bYyEVItcJYPLXnQPYQVK8NrT9IoJlKaVfqpXG2lii2o",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zvHWX359A3CvfJnCYaAiAde",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "secp256k1",
        "kid": "bYyEVItcJYPLXnQPYQVK8NrT9IoJlKaVfqpXG2lii2o",
        "x": "pH8icNZgUCwcX5P-YaLO212N9-BqyyUlDnrLijmZh7g",
        "y": "z83kLTM784_3QLELR4FBnSr58HG_bL75ufcZ0y3yy5U",
        "alg": "ES256"
      }
    }
  ],
  "authentication": [
    "did:ebsi:zvHWX359A3CvfJnCYaAiAde#F0r5Oyt_lahvvz6MWlYs3mcYNKZiiQdUfqv8tshHN9w" // DID 1 key to authenticate
  ],
  "assertionMethod": [
    "did:ebsi:zvHWX359A3CvfJnCYaAiAde#F0r5Oyt_lahvvz6MWlYs3mcYNKZiiQdUfqv8tshHN9w" // DID 1 key to sign claims
  ],
  "capabilityInvocation": [
    "did:ebsi:zvHWX359A3CvfJnCYaAiAde#HnlK0wApxuRLLuCl1d1N3eL0_1ZvnNa3oBsTpBL1FNU", // DID 1 key to control did documents / EBSI Platform
    "did:ebsi:zvHWX359A3CvfJnCYaAiAde#bYyEVItcJYPLXnQPYQVK8NrT9IoJlKaVfqpXG2lii2o"  // DID 1 cold storage key
  ]
}

---- Bounded DID document ----
{
  "@context": "https://w3id.org/did/v1",
  "id": "did:ebsi:zxA9t4Z2uorEVnx9njWUYvR",
  "controller": [
    "did:ebsi:zvHWX359A3CvfJnCYaAiAde",
  ],
  "verificationMethod": [
    {
      "id": "did:ebsi:zxA9t4Z2uorEVnx9njWUYvR#Ajo-JS9ai-hfuaYX6HwgQGBqZogTEPBCm0rMEF5CQx0",
      "type": "JsonWebKey2020",
      "controller": "did:ebsi:zxA9t4Z2uorEVnx9njWUYvR",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-256",
        "x": "g-foMvQQEANWgL3RXy3pu-gYdcG3Em9W245UNXiYwhs",
        "y": "fowb8W13LEjvyfeiJDep6ivw9oimh2mjt28_SSckBOI",
        "alg": "ES256"
    }
  ],
  "assertionMethod": [
    "did:ebsi:zxA9t4Z2uorEVnx9njWUYvR#Ajo-JS9ai-hfuaYX6HwgQGBqZogTEPBCm0rMEF5CQx0"
  ]
}

info

Please check our guidelines to learn how to register a DID document

Security considerations

EBSI DIDs operate under the Internet Threat Model, defined in Section 3 of the IETF RFC - 3552.

This specification defines the format and content of DIDs and DID documents. Both of these entities are public and are registered in the EBSI DID Registry in a tamper-proof manner. Registration of DIDs and DID documents requires authorisation and authentication, and actions must be signed. This procedure eliminates the need for additional integrity protection mechanisms. Anonymous or unrestricted access to these entities does not compromise security implementations.

One or more public keys can be bound to a DID, and the DID method supports adding new keys, key rolling and key deactivation. These operations can be performed only by parties who control the DID controlling key. For private key security, see Security considerations: Private Keys.

The DID controller can bind one or more public keys to their DID. If an attacker gains control of the key management key, they can bind their own keys to the DID or invalidate other DID keys. Therefore, it is crucial for the DID controller to sufficiently protect the DID managing keys. It is strongly discouraged to use a single DID key for both DID updates and signing. Using separate key pairs for signature and key management provides several benefits to users. The ramifications associated with the loss or disclosure of a signature key differ from the loss or disclosure of a key management key. Using separate key pairs permits a balanced and flexible response.

Privacy considerations

This DID method is intended for Legal Entities. Personal public keys and personal information must not be stored in the DID document.

Implementers must follow the latest ETSI, ENISA, and NIST security guidelines for key management in (mobile) applications and for the secure storage of personal data, whether on-site or in the cloud, including the use of Transport Layer Security (TLS) for secure data transmission.