Purpose of this document
This specification defines the profile for a W3C-compliant, privacy-preserving, and GDPR-compliant DID method key. The DID method must be used for Natural Persons and can be used for Legal Entities that do not require formal accreditations or key-rotation capabilities. DID methods serve as the means to create, resolve, update, and deactivate a specific DID type and its corresponding DID document.
Context
This specification addresses the EBSI profile for the did:key method, which is used for Natural Persons in the EBSI ecosystem. It is important to note that:
- As a European initiative, EBSI operates under the European Regulation for electronic identification and trust services, commonly referred to as eIDAS (providing explicit specifications for identity using a centralised approach), and
- EBSI also operates within the framework of the General Data Protection Regulation (GDPR), which defines regulations on data protection and privacy in the EU and the European Economic Area, and
- The Decentralised Identifier (DID) concept, which originated in the context of the W3C, enables an entity to self-identify, which is commonly referred to as self-sovereignty. W3C maintains an interoperability registry for Decentralized Identifiers, where in-progress DID methods are listed.
EBSI's DID method adheres to the eIDAS and GDPR regulations, as well as the Decentralised Identifier concept. It is important to consider that the self-sovereignty principle, which allows the user to decide which personal information they disclose, must be balanced with the legitimate requirements of the party with whom the user interacts.
A DID is linked to a DID document containing, among other things, a public key. The corresponding private key is stored under the control of the subject or controller, a topic not addressed by the W3C DID specifications. The connection is established through the id property of the DID document, which contains the corresponding DID. In an eIDAS context, two topics are particularly relevant for an EBSI DID:
- The private key, corresponding to the DID's public key, must be generated, managed and used securely.
- A DID and its supporting elements must satisfy the respective eIDAS level of assurance before being bound to an eIDAS identity with a specific level of assurance.
For more information, see Identification and Trust Services 910/2014, Trusted Lists - 2013/662/EU and related implementing acts.
Glossary
| Name | Meaning |
|---|---|
| EBSI | European Blockchain Services Infrastructure |
| DID | Decentralised Identifier |
| MSI | Method-specific identifier |
| GDPR | General Data Protection Regulation |
| eIDAS | European Regulation for electronic identification and trust services |
Method syntax
This document defines a profile for the did:key method and provides additional information about security, privacy, and usage.
DID name and schema
- DID method name: key
- DID syntax: did:key :[method-specific-identifier]
DID creation
The method-specific identifier (MSI) must be unique and case-sensitive. Since the MSI is the public key, securely generating and managing the keys is crucial. Private keys are typically generated by (pseudo-)random number generators (PRNG) within hardware (e.g., Hardware Security Module, secure device element, etc.) or software environments. Poorly designed PRNGs will lead to deterministic key generation, causing key and DID collisions and lowering the attack barrier. To prevent public key or DID collision and ensure secure key generation, attested PRNGs must be software or hardware-based.
DID and DID private keys must be stored securely in accordance with the latest key management security practices. Examples include (certified) Hardware Security Modules, secure elements in mobile devices, and encrypted storage. Key compromise may lead to identity and personal information theft or allow an adversary to access users' online accounts. Access to the private key must be managed to ensure only the key owner has access to it. Additional security measures must be considered when sole control needs to be guaranteed.
See ETSI - The framework for standardization of signatures and references within. Key access management may require support for hardware authentication devices, 2FA mechanisms, biometric authentication, and similar methods.
All relevant security recommendations and implementing acts pertaining to the domain in which the keys are used must be considered.
EBSI encourages using SOG-IS-approved cryptographic algorithms for key pairs (SOG-IS agreed Cryptographic Mechanisms) and, at a minimum, requires support for Elliptic Curve NIST P256 private and public keys.
Schema of the method-specific-identifier
The MSI is always encoded in multibase:base58btc format (Multibase); thus, the identifier always starts with the character "z". The rest of the identifier consists of a byte array. The MSI assures a 1-to-1 correspondence between the DID and the public key (the same public key cannot result in different DIDs, and different DIDs cannot resolve to the same public key).
The MSI can be presented as multibase.base58btc(multicodec.jwk_jcs-pub([serialised public key])).
| User | Multibase encoding | Multi codec | Serialises public key | Total Size |
|---|---|---|---|---|
| Natural Person | Base58btc | jwk_jcs-pub (0xeb51) | JSON object containing only the required members of a JWK (as defined in RFC7638, section 3) representing the public key, and serialisation based on JCS (as defined in RFC8785), encoded as UTF-8. | Contingent on the key size |
The JWK must be constructed as defined in RFC7638: Create a JSON object (RFC7159) containing only the required members of a JWK, which represents the public key. There should be no whitespaces or line breaks before or after any syntactic elements, and the required members should be ordered lexicographically based on the Unicode (UNICODE) code points of the member names. (This JSON object constitutes a valid JWK representation of the key.)
You can use the did:key DID generator below to see how it works.
DID document
The subject presents only the DID to the issuer or verifier (as part of the Verifiable Credential and Verifiable Presentation) since the DID document is resolved from the DID itself, as presented in this section. The key DID document is derived from a single public key in JWK format, while the rest of the DID document follows a template.
- The DID is decoded into a byte array
- The serialised JWK is extracted
- The JWK is decoded into a JWK format
The DID document's verification method type must be JsonWebKey2020.
Resolving the DID and DID document
DIDs and DID documents are not publicly resolvable; however, the DID document can always be reconstructed from the DID, and the DID can always be reconstructed from a public key. The DID document must be viewed as a ephemeral object that can always be reconstructed from a public key or DID. All DID signed content must be verified by using the reconstructed DID document. DID equality can be achieved through simple string equality, as the encoding algorithm is deterministic.
Please check our guidelines to learn how to register a DID document
Signing and issuing
All DID document properties can be used interchangeably, as all of them refer to the same public key, and the DID document is constructed from a single public key. Authentication should be used when signing Verifiable Presentations, while assertionMethod should be used for self-issuing Verifiable Credentials.
Updating or deactivating
The DID is derived from a public key, and DID updates are currently not supported. DIDs and DID keys can be suspended or revoked indirectly by suspending or revoking the Verifiable Credentials issued to the DID. Deletion of the private key will effectively deactivate the DID, but it does not terminate the existence of the DID or prevent its reactivation.
Example
---- ALICE ----
{
'@context': [
'https://www.w3.org/ns/did/v1',
'https://w3id.org/security/suites/jws-2020/v1'
],
id: 'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r',
verificationMethod: [
{
id: 'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r',
type: 'JsonWebKey2020',
controller: 'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r',
publicKeyJwk: {
crv: 'P-256',
kty: 'EC',
x: 'ngy44T1vxAT6Di4nr-UaM9K3Tlnz9pkoksDokKFkmNc',
y: 'QCRfOKlSM31GTkb4JHx3nXB4G_jSPMsbdjzlkT_UpPc'
}
}
],
authentication: [
'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r'
],
assertionMethod: [
'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r'
],
capabilityInvocation: [
'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r'
],
capabilityDelegation: [
'did:key:z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r#z2dmzD81cgPx8Vki7JbuuMmFYrWPgYoytykUZ3eyqht1j9KbsEYvdrjxMjQ4tpnje9BDBTzuNDP3knn6qLZErzd4bJ5go2CChoPjd5GAH3zpFJP5fuwSk66U5Pq6EhF4nKnHzDnznEP8fX99nZGgwbAh1o7Gj1X52Tdhf7U4KTk66xsA5r'
]
}
Security considerations
EBSI DIDs operate under the Internet Threat Model, as defined in Section 3 of the IETF RFC3552.
This specification defines the format and the content of DIDs and DID documents. Since DIDs and DID documents are derived from a public key deterministically, no additional integrity service is required. Neither the DID nor the DID document need to be kept secret, and unrestricted, anonymous access to the DID and DID document has no security implications. Since there is a one-to-one relationship between a DID and a public key, and the DID is deterministically derived from the public key, no additional security measures are required to ensure the binding between the two.
For private key security, see Security considerations: Private Keys.
Privacy considerations
Public keys, DIDs, and DID documents controlled by Natural Persons are considered personal data; thus, Regulation (EU) 2016/679 (General Data Protection Regulation) applies. Such DIDs and corresponding DID documents will be created and stored in personal digital wallets and used in protocols with issuers of Verifiable Credentials and verifiers of Verifiable Presentations. Software providers developing wallets that will handle and process this personal data are classified as Data Processors and Controllers and must obtain consent from the data subjects and adhere to GDPR regulations.
EBSI DIDs operate under the Internet Threat Model, as defined in Section 3 of the IETF RFC3552. This section contains a variety of privacy considerations that individuals using the EBSI DID methods for natural persons are advised to consider. Its starting point is the RFC6973: Privacy Considerations - Section 5, which lists threats relevant to using the EBSI DID method that must be mitigated.
Privacy threats
The key DID should be considered a pseudonym for identity; it is trackable and can be correlated. A DID is a part of every Verifiable Credential and Verifiable Presentation. End-users should use multiple DIDs to mitigate traceability and correlation, but this also requires that each DID appears only in a single Verifiable Credential. Having multiple DIDs with the same Verifiable Credential content allows correlation and identification through the content of the Verifiable Credential.
Verifiable Presentations and Verifiable Credentials "Terms of Use" can be breached by the Verifier or Issuer acting as one without notification of the act. All content that is shared with third parties is subject to privacy threats; therefore, the end-user should carefully evaluate what to send and to whom. The end-user has complete control over all explicit data, and it is the end-user's decision to consent to the disclosure.
It is recommended to issue only one personal Verifiable Credential to a given DID to minimize user traceability. However, the same VC may be issued to multiple DIDs controlled by the DID controller.
Generic notes
This specification offers no additional protection against surveillance, nor does it endorse it. All data related to the key are stored by the wallet implementer in the form and location of their choice, but it must be outside of the EBSI Platform. The stored data includes Verifiable Credentials, Private keys, DIDs, and DID documents.
Implementers must follow the latest ETSI/ENISA/NIST security guidelines for key management (mobile) applications, storing personal data on-site in the cloud, and TLS.
Verifiable Credentials may be revoked, but doing so does not remove the contained data; it merely terminates the private key owner's usage of the Verifiable Credential.