Purpose of this document
This specification defines the profile for a W3C-compliant, privacy-preserving and GDPR-compliant did:key method. This DID method must be used for Natural Persons and can also 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 details 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, known as eIDAS, which provides explicit specifications for identity using a centralised approach.
- 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.
- The Decentralised Identifier (DID) concept, originally from the World Wide Web Consortium (W3C), enables entities to self-identify, often referred to as self-sovereignty. W3C maintains an interoperability registry for Decentralized Identifiers, where in-progress DID methods are listed.
EBSI's did:key method complies with eIDAS and GDPR regulations, as well as the DID concept. It is important to balance the self-sovereignty principle, which allows users to decide which personal information they disclose, with the legitimate requirements of interacting parties.
A DID is linked to a DID document containing, among other things, a public key. The corresponding private key is stored and managed by 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. Within the eIDAS context, two aspects 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 on 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. As the MSI contains the encrypted public key, it is crucial to securely generate and manage the keys. Private keys are typically generated by (pseudo-)random number generators (PRNG) within hardware (e.g., Hardware Security Module, secure device elements, etc.) or software environments. Poorly designed PRNGs can lead to deterministic key generation, resulting in 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.
DIDs and private keys must be stored securely according to the latest key management security practices. Examples include (certified) Hardware Security Modules, secure elements in mobile devices and encrypted storage. Key compromise can 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. Additional security measures must be considered when sole control must be guaranteed.
See ETSI - The framework for standardization of signatures and references within. Key access management may require support for hardware authentication devices, two-factor authentication (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 one-to-one correspondence between the DID and the public key (the same public key cannot generate 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 | Multicodec | Serialised 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 JSON Web Key (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 whitespace 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.
Use the did:key DID generator below to see how it works.
To ensure proper operation, the decoded value must be assigned to the multicodecValue variable after performing varint decoding. For further clarification, please consult this page.
DID document
When presenting a Verifiable Credential (VC) or Verifiable Presentation (VP), the subject only provides the DID to the Issuer or Verifier. The DID document is resolved from the DID itself, as outlined in this section. The did:key DID document is derived from a single public key in JWK format, and the remaineder of the DID document follows a predefined template.
The process to construct the key DID document from the did:key DID is as follows:
- Start with a DID in the format:
did:key:[method-specific-identifier]. - Decode the method-specific identifier into a byte array.
- Extract and decode the serialised JWK into 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 an ephemeral object that can always be reconstructed from a public key or DID. All DID-signed content must be verified using the reconstructed DID document. DID equality can be achieved through simple string equality, as the encoding algorithm is deterministic.
Please consult our guidelines for more information on how to register a DID document
Signing and issuing
All DID document properties can be used interchangeably, as they all refer to the same public key, and the DID document is constructed from a single public key. Authentication should be used when signing VPs, while assertionMethod should be used for self-issuing VCs.
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 VCs 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 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. 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.
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 VCs and Verifiers of VPs. 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 VC and VP. End-users should use multiple DIDs to mitigate traceability and correlation, but this also requires that each DID appears only in a single VC. Having multiple DIDs with the same VC content allows correlation and identification through the content of the VC.
VPs and VCs "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 VC to a given DID to minimise 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 VCs, Private keys, DIDs, and DID documents.
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.
VCs may be revoked, but doing so does not remove the contained data; it merely terminates the private key owner's usage of the VC.