The did:cel Method v0.3

This specification optimizes for the following design goals:

Minimal Infrastructure

A single individual with a file hosting location can create and control multiple DIDs in a way that the identifiers are highly-available and globally recognized.

Near-zero Cost

The cost to create and control multiple DIDs is not burdensome to at least 70% of the world's population, which are the number of people that have access to the Internet as of 2025.

Censorship and Coercion Resistant

The witness and file storage services used to manage a DID cannot censor or coerce an individual or organization to any significant degree.

No Centralization

Witness and file storage services are abundant, easy to operate at scale, and are easily interchangeable if they become non-responsive or compromised.

Readers might also find the Goals section in the Cryptographic Event Log v0.1 specification of interest.

The following focal use cases have been identified as ones that this specification is capable of addressing.

Self-hosted Management

Joe would like to create and manage his DIDs using software and infrastructure that he controls.

Custodial Management

Wilhelm would like to use DIDs but does not have the technical expertise to self-host and uses a well-reviewed service provider to manage his DIDs on his behalf, but enables his friends to help him leave the service if they work against his interests.

Organizational Management

LittleCorp uses DIDs that represent operational divisions within the organization to issue verifiable credentials . The organization's security requirements related to government-approved cryptography, key rotation requirements, and recoverability after compromise are all addressable with the did:cel DID method .

Readers might also find the Use Cases and Requirements section in the Cryptographic Event Log v0.1 specification of interest.

The interaction flow between DID controllers , witness services, storage services, and verifiers follows a standard process. When a DID controller creates or updates a DID document , they generate a signed event and append it to their cryptographic event log , creating a hashlink to the previous event. The controller then sends a cryptographic hash of this event to their chosen witness services, which each generate a data integrity proof attesting that they saw the cryptographic hash at a particular time, and then return the witness proof to the controller. The controller collects these witness proofs, attaches them to the event in the log, and publishes the complete cryptographic event log to one or more storage services.

When a verifier needs to validate a DID , the controller provides the DID and a storage location that can be used to retrieve the cryptographic event log from the storage services. The verifier then downloads the log and verifies the hashlinked chain integrity. It does this by checking that operation proofs are signed by authorized keys from the DID document , the hashlinks are correct, the operations performed are valid, and ensures that witness proofs meet their requirements. This separation of concerns between controllers, witnesses , storage, and verification enables a fully decentralized system where no single party has unilateral control.

Some terminology used throughout this document is defined in the Terminology section of the Controlled Identifiers v1.0 specification, the Terminology section of the Decentralized Identifiers (DIDs) v1.0 specification, and the Terminology section of the Verifiable Credential Data Integrity 1.0 specification. This section defines additional terms used throughout this specification.

cryptographic event log

A hashlinked chain of events that records the complete history of operations performed on a document with each event cryptographically tied to the preceding event.

hashlink

A mechanism of connecting data through cryptographic hashes such that an observer can cryptographically verify that the contents of the data that is pointed to has not been modified since the link was created.

self-certifying identifier

A type of identifier derived directly from the cryptographic hash of data. The approach creates an intrinsic binding between the identifier and its content without requiring external registration or validation.

witness

An independent entity that provides cryptographic attestation to data in a cryptographic event log by creating data integrity proofs , enabling distributed validation without needing to store or control the data being attested to. Multiple witnesses can attest to the same data, and the process of creating such attestations is called witnessing .

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY MUST , MUST OPTIONAL , and SHOULD in this document are to be interpreted as described in BCP 14 [ RFC2119 ] [ RFC8174 ] when, and only when, they appear in all capitals, as shown here.

The cryptographic event log ( cryptographic event log ) for a DID is designed to be publicly verifiable, which means that the complete history of DID document operations, including creation, updates, additions, and removals of verification methods and services, is permanently recorded and accessible. This transparency enables auditability and trust but comes at the cost of revealing temporal patterns and the evolution of a DID's capabilities over time. Observers can analyze the log to determine when verification methods were added or expired, when services were introduced or removed, and how frequently the DID document has been modified.

To mitigate this privacy concern, implementers might carefully consider what information is included in DID documents and when updates are performed. Batch multiple related changes into a single update operation when possible to reduce the granularity of information exposed through temporal analysis. For use cases requiring higher privacy, consider using ephemeral DIDs that are rotated regularly, or employing DIDs with shorter active periods for their event logs. Organizations might also document their DID Document update policies to help users understand the privacy implications of using their DID -related services.

The cryptographic event log architecture relies on witness services to provide attestations for DID operations. The specific set of witnesses chosen to attest to an event can serve as a correlatable fingerprint, especially if the witness configuration is unique or rarely used. If a DID consistently uses the same set of witnesses across multiple operations, or if the witness selection pattern is distinctive, observers might be able to correlate different DIDs or activities as belonging to the same entity or organization. This correlation risk increases when custom witness services are deployed or when non-standard witness configurations are used.

To reduce correlation risk, implementers might use commonly deployed and widely adopted witness services when privacy is a concern. Using the same witness configuration as other entities in the ecosystem provides herd privacy by making it difficult to distinguish one DID controller from another based solely on witness selection. Standardizing witness selection policies across an ecosystem can also help establish common configurations that enhance privacy through ubiquity.

Each event in the cryptographic event log includes temporal information, either explicitly through timestamps in witness proofs or implicitly through the sequence and timing of operations. This temporal metadata can reveal patterns about the DID controller's activities, operational hours, time zones, or response times to security incidents. For example, if verification methods are consistently updated during specific hours, this might reveal information about the organization's business hours or geographic location. Rapid succession of updates might indicate automated processes or security incidents, while long periods of inactivity followed by bursts of activity can reveal operational patterns.

Implementers can mitigate temporal metadata leakage by implementing delays or jitter in update operations to obscure the precise timing of changes. Automated systems might avoid predictable update schedules and instead use randomized timing within acceptable windows. For sensitive operations, consider batching updates and releasing them at randomized intervals to prevent timing correlation. Organizations might also be aware that even without explicit timestamps, the sequence of events and witness attestation timing can leak temporal information, so careful consideration of when to perform DID operations is important for privacy-sensitive use cases.

The hashlinking mechanism that chains events together in the cryptographic event log provides strong integrity guarantees but also creates an immutable, permanent record of all DID operations. Once an event is added to the log, witnessed , and stored, it cannot be removed or modified without breaking the cryptographic chain. This means that information about previous verification methods, services, or other metadata remains permanently visible in the log even after being removed from the current DID document . This immutability can be problematic for privacy if sensitive information was inadvertently included in earlier versions of the DID document , or if the history of changes itself reveals sensitive information about the DID controller 's activities or relationships.

To address the immutability concern, implementers might exercise caution when including information in DID documents , as any data added will become part of the permanent record. Before performing operations, carefully review the information being added to ensure it does not contain sensitive data that needs to remain private. For cases where the historical record becomes problematic, DID controllers can deactivate the current DID and create a new one, though this breaks continuity and requires updating all systems that reference the old DID. Alternatively, implement clear documentation and guidelines for DID controllers about what information might and might not be included in DID documents to prevent privacy issues before they occur.

A DID identifier in the did:cel method is derived from cryptographic material from the initial creation event, making it a persistent self-certifying identifier that is correlatable across all uses. Unlike some privacy-preserving identifier systems that allow for easy rotation or unlinkable presentations, a did:cel identifier remains constant and serves as a permanent correlation point. Any entity that observes the DID identifier in multiple contexts can definitively link those interactions as involving the same DID controller . This persistence is valuable for establishing long-term identity and trust but directly conflicts with privacy goals that require unlinkability between different interactions or contexts.

For scenarios requiring unlinkability, implementers might not reuse the same DID across different contexts or relationships. Instead, create separate DIDs for different purposes, relationships, or contexts where correlation might be prevented. Implement DID management practices that include regular rotation of DIDs when appropriate, and clearly document which DIDs are used for which purposes. Organizations might also provide tooling to help users manage multiple DIDs and understand the privacy implications of DID reuse. For use cases where both persistence and privacy are required, consider layering additional privacy-preserving mechanisms on top of the DID infrastructure, such as using verifiable credentials with unlinkable presentation features.

DID documents contain verification methods that specify the cryptographic keys and their purposes (authentication, assertion, key agreement, etc.). The complete set of verification methods, their types, cryptographic algorithms, and relationship assignments can serve as a unique fingerprint for a DID, especially when non-standard cryptographic suites are used or when the combination of verification methods is unusual. Even when using common cryptographic suites, the specific number and configuration of verification methods for different purposes can reveal information about the DID controller's intended use cases, security posture, or organizational structure.

To reduce the identifiability of DIDs through verification method enumeration, implementers might favor standard, commonly used verification method configurations that are widely deployed in the ecosystem. Avoid creating unique or unusual combinations of verification methods unless specifically required. When possible, use the minimum number of verification methods necessary for the intended functionality to reduce the uniqueness of the configuration. For organizations deploying multiple DIDs , consider standardizing on common verification method templates that are used across many DIDs to prevent fingerprinting. Documentation might also guide users on recommended verification method configurations that balance functionality with privacy considerations.

DID documents can include service endpoints that specify how to interact with services related to the DID controller . These service endpoints often contain URLs or other network identifiers that reveal information about the DID controller's infrastructure, service providers, or operational environment. Service endpoints might point to specific servers, domains, or third-party services, which can be used to correlate DIDs , identify the organizations or individuals behind them, or map out relationships between different entities. Even when service endpoints use common infrastructure, the specific combination or configuration of services can serve as an identifying characteristic.

Implementers might carefully consider whether service endpoints need to be included in the DID document itself, or whether they could be communicated through other channels that provide better privacy properties. When service endpoints might be included, use generic or shared infrastructure that does not reveal specific information about the DID controller . Consider using privacy-preserving relay services, proxy servers, or shared service infrastructure that is used by multiple entities to prevent correlation. Avoid including service endpoints that point to unique or rarely used domains. For higher privacy scenarios, service endpoint information might be exchanged out-of-band or through encrypted communication channels rather than being published in the public DID document .

When witness services attest to cryptographic event log events, they create proofs that include metadata such as their witness identifier, the cryptographic suite used, and timing information. While this metadata is necessary for verification, it can also reveal information about the DID controller 's relationships with witness services, their witness selection strategy, and potentially their geographic location or operational preferences. If a DID consistently uses witnesses that are associated with specific geographic regions, industries, or organizations, this association can reveal information about the DID controller . Additionally, the specific combination of witness services chosen might reveal business relationships or trust relationships that the DID controller has established.

To mitigate privacy concerns related to witness metadata, implementers might select witness services that are widely used and geographically distributed to avoid revealing location information. When possible, use witness services that are operated by neutral, well-known entities rather than industry-specific or organization-specific witnesses that might reveal affiliations. Documentation might guide users on selecting witness services that align with their privacy requirements, and ecosystems might encourage the deployment of diverse, broadly available witness services that can be used interchangeably to enhance herd privacy.

The cryptographic algorithms and key types chosen during DID creation and throughout the DID's lifecycle represent long-term commitments that are permanently recorded in the cryptographic event log . These cryptographic choices can reveal information about when the DID was created (based on algorithm popularity at that time), the security requirements or preferences of the DID controller , and potentially the systems or software used to create the DID. As cryptographic algorithms age and new algorithms are adopted, the continued use of older algorithms or the early adoption of newer ones can serve as identifying characteristics. Furthermore, the cryptographic choices reveal the DID controller 's security posture and risk tolerance.

Implementers might provide clear guidance on recommended cryptographic algorithms that balance security requirements with privacy considerations. Using widely adopted, current best-practice cryptographic algorithms helps provide herd privacy by ensuring that many DIDs share similar cryptographic profiles. Organizations might plan for cryptographic agility by supporting algorithm migration paths that allow updating to newer algorithms without requiring DID replacement. When upgrading cryptographic algorithms, coordinate with broader ecosystem adoption to avoid standing out as an early or late adopter. Documentation might explain the privacy implications of different cryptographic choices and provide recommendations for standard configurations that are appropriate for different use cases.

Resolving a DID to obtain its current DID document and verify the cryptographic event log requires accessing the log data, which is stored in various locations. The act of resolving a DID can reveal information about the resolver's interest in that particular DID to the entities operating the storage or retrieval infrastructure. This creates potential for surveillance, tracking of resolution patterns, or profiling of which DIDs are being resolved by which entities. Network-level metadata such as IP addresses, timing of resolution requests, and patterns of correlated resolutions can further compromise privacy by revealing resolver identity or activities.

To enhance resolution privacy, implementers might use privacy-preserving resolution mechanisms such as proxies, Oblivious HTTP, VPNs, or onion routing when resolving DIDs. Aggressive caching of DID documents and cryptographic event log data reduces the frequency of resolution requests and limits the metadata exposed to storage providers. Consider using decentralized resolution infrastructure that does not rely on single points that can monitor resolution patterns. Implement resolution protocols that minimize metadata leakage, such as fetching data through encrypted channels or using obfuscation techniques that prevent correlation of multiple resolution requests. For high-privacy scenarios, design systems that pre-fetch or batch resolve multiple DIDs to obscure which specific DIDs are of interest, and utilize privacy-preserving query protocols where available.

The security of the cryptographic event log relies on witness services providing independent attestations to DID document operations. If a sufficient number of witnesses collude or are compromised by an attacker, they could deny witnessing calls from specific IP addresses or generate invalid proofs to deny a DID controller the ability to witness a particular event. The impact of such an attack depends on how many witnesses are required for an event to be considered valid and how many witnesses an attacker can control. If witnesses are operated by a single entity or share common infrastructure, the risk of coordinated compromise increases significantly.

To mitigate witness collusion risks, implementers are encouraged to select witnesses operated by independent entities with diverse operational and jurisdictional characteristics. Systems that verify DIDs can require attestations from a minimum number of witnesses before accepting an event as valid, and can maintain lists of trusted witnesses with known good security practices. DID controllers are encouraged to select geographically and organizationally distributed witnesses to minimize the risk of coordinated attacks. Monitoring witness behavior over time can help detect anomalies that might indicate compromise, such as witnesses consistently refusing to signing events that other witnesses sign. For critical applications, implementing witness rotation policies or requiring attestations from a larger pool of witnesses can provide additional security margins.

When a cryptographic key used in a DID document is compromised or needs to be rotated for operational reasons, the DID controller faces the challenge of updating the DID document while maintaining the integrity and verifiability of the cryptographic event log . The key rotation process itself requires signing operations using existing keys, but if those keys are compromised, an attacker might perform unauthorized rotations before the legitimate DID controller can act. Additionally, the immutable nature of the log means that compromised keys remain visible in the historical record, potentially allowing attackers to forge signatures on historical DID documents if proper expiration handling is not implemented.

Implementers are encouraged to implement key expiration mechanisms using the expires property on verification methods , which limits the time window during which a compromised key can be abused. When rotating keys, DID controllers are advised to follow a process of first adding new keys to the DID document , then expiring old keys, and only after confirming the new keys are functional should the old keys be removed. This overlapping approach ensures continuity of operations during rotation. For critical keys, maintaining offline backup keys with authority to perform emergency rotations can provide recovery paths when primary keys are compromised. Conforming systems that verify data integrity proofs check verification method expiration times and reject proofs created after a verification method has expired, limiting the damage from compromised keys. Regular key rotation schedules, even without evidence of compromise, can reduce the impact window of undetected key compromises.

The did:cel method relies on SHA3-256 cryptographic hashing for multiple security-critical functions: generating DID identifiers from DID documents , creating hash links between events in the cryptographic event log , and ensuring the integrity of the event chain. If SHA3-256 were to become vulnerable to collision attacks where two different inputs produce the same hash output, attackers could create fraudulent DID documents that resolve to the same DID identifier, forge event chain links to hide modifications, or substitute malicious events while maintaining apparent chain integrity. The security of the current DID method depends on the continued collision resistance of SHA3-256, though upgrading to a newer cryptographic hashing algorithm is possible and supported.

While SHA3-256 is currently considered cryptographically secure with no known practical collision attacks, implementers are advised to monitor cryptographic research for any developments that might weaken SHA3-256. Systems can be designed with cryptographic agility in mind, allowing for future migration to stronger hash functions if SHA3-256 becomes compromised. When verifying DIDs , conforming implementation validate not just that hash links are correctly formed, but also that the entire chain of events maintains integrity from the creation event forward. For long-lived DIDs , DID controllers might consider planning for eventual migration to stronger cryptographic primitives before SHA3-256 reaches end of life, though the timeline for such migrations is measured in decades given current cryptographic knowledge.

Events in the cryptographic event log contain data integrity proofs and witness attestations that are valid cryptographic signatures. Without proper safeguards, an attacker might capture a valid event from one DID 's log and attempt to replay it in a different context, such as in another DID 's log or at a different position in the same log. While the hashlinking mechanism provides some protection by binding events to specific positions in the chain, attackers might attempt to fork a log at an earlier point and replay captured events to create a fraudulent alternate history. The self-contained nature of events means that signatures remain mathematically valid even when presented out of their intended context.

The hashlinking of events through the previousEventHash property provides the primary defense against replay attacks by binding each event to a specific position in the event chain. Conforming implementations that verify cryptographic event logs validate that each event's previousEventHash hash correctly matches the hash of the preceding event, and that the chain is unbroken from the creation event to the most recent event. Systems that maintain state about known DIDs can track the highest event sequence number they have seen for each DID and reject events that appear to rewind the log.

The cryptographic event log creates a linear chain of events through hashlinking , but without additional coordination mechanisms, a DID controller or an attacker with access to the DID controller 's keys could create multiple divergent chains (forks) from the same parent event. This could result in different observers seeing different versions of the DID document depending on which fork they have accessed. A compromised or malicious DID controller might try to selectively present different forks to different verifiers ], creating confusion about the authoritative state of the DID document .

Detecting forks requires verifiers to compare event logs from multiple cryptographic event log storage services listed in the DID Document history and identify cases where divergent chains exist for the same DID . The cryptographic event log storage services-based architecture provides fork detection that is independent of the witness services. Clear policies about how verifiers handle fork detection, such as "longest fork always wins", and whether cryptographic event log services alert each other or DID observers, can strengthen the overall security posture against forking attacks.

Each event in a cryptographic event log contains data integrity proofs on the operation and one or more witness proofs attesting to the event. Verifying the complete log requires checking every proof in every event from the creation event forward, which involves cryptographic signature verification operations, hash computations, and canonicalization of JSON data structures. For DIDs with long histories containing many events and witness proofs, the computational cost of full verification can be significant, potentially leading to resource exhaustion or denial-of-service conditions when processing maliciously crafted logs with excessive events or operation data.

Implementations are encouraged to set reasonable limits on the resources they will expend when verifying cryptographic event logs , including maximum numbers of events to process, maximum verification time, and maximum memory usage. When possible, verification can be optimized by caching the results of verifying earlier portions of the log and only verifying new events since the last cached verification point. For applications that do not require complete historical verification, implementations might depend on the cryptographic event log storage services to verify the history since they are not supposed to accept cryptographic event logs with malformed histories. Rate limiting the acceptance of DID resolution requests can prevent attackers from overwhelming systems with verification requests for complex DID documents . Clear documentation about the expected verification costs and performance characteristics helps implementers make informed decisions about resource allocation for DID verification operations.

The witness -based architecture of did:cel creates an operational dependency on witness services being available and responsive when DID controllers need to update their DID documents . If witnesses become unavailable due to network outages, operational failures, or deliberate denial-of-service attacks, DID controllers might be unable to record new events in their cryptographic event logs , effectively preventing them from making necessary updates such as key rotations in response to security incidents. This availability dependency could be exploited by attackers who compromise a DID controller 's keys and then launch denial-of-service attacks against witness services to prevent the legitimate controller from performing emergency key rotations.

DID controllers are encouraged to select multiple geographically and operationally distributed witnesses to reduce the risk of correlated failures. Systems can be designed to tolerate some witness unavailability by requiring only a subset of witnesses to attest to an event, though this reduces the security assurance provided by witness attestations. Implementing witness selection policies that automatically failover to alternative witnesses when primary witnesses are unavailable can maintain operational continuity during outages. For critical operations, DID controllers might pre-establish relationships with backup witness services that can be used if primary witnesses fail. Witness services are encouraged to implement high-availability architectures with redundancy and failover capabilities to minimize downtime. Clear service level agreements and monitoring of witness availability helps DID controllers make informed decisions about which witnesses to rely on for their security requirements.

The did:cel method uses modern cryptographic signing and hashing algorithms. While these cryptographic algorithms are currently considered secure, all cryptographic algorithms have a finite lifetime and eventually become vulnerable to attacks as computational capabilities advance or new cryptographic breakthroughs occur. DIDs created today might need to remain valid and verifiable for many years or decades, potentially outliving the security guarantees of the cryptographic algorithms they employ. As algorithms age, signatures and hashes created using those algorithms provide diminishing security. The immutable nature of the cryptographic event log means that while historical events cannot be re-signed with stronger algorithms, the historical chain of events can be signed with stronger algorithms (such as post-quantum signatures) under certain conditions (such as the security of SHA3-256 remaining uncompromised even if ECDSA becomes compromised).

DID controllers planning for long-term use of their DIDs are encouraged to monitor cryptographic algorithm recommendations and plan for upgrading algorithms or eventually migrating to DIDs using stronger algorithms before current algorithms are compromised. Implementing cryptographic layering by including multiple verification methods using different cryptographic algorithms, such as pre-quantum and post-quantum cryptographic algorithms, can provide continued security even if one algorithm is compromised, following the guidance in the Verifiable Credential Data Integrity 1.0 specification. Systems that verify DIDs can maintain policies about which cryptographic algorithms are acceptable and reject DIDs using deprecated algorithms that no longer provide adequate security. For historical preservation, the witness attestations in the log provide evidence that events were considered valid at the time they were created, even if the underlying cryptographic algorithms later become compromised. Clear documentation about the expected lifetime of cryptographic algorithms helps DID controllers plan appropriate migration timelines.

Witness data integrity proofs include timestamp information indicating when the witness attested to an event. While timestamps can be useful for understanding the temporal sequence of events and detecting anomalies, they also introduce potential for manipulation if witnesses collude or if their clocks are inaccurate or maliciously adjusted. An attacker who compromises multiple witnesses might create backdated attestations to make fraudulent events appear to have occurred earlier than they actually did, or forward-date attestations to hide the timing of malicious activities. Relying on timestamps for security-critical decisions can be problematic given the difficulty of ensuring accurate, tamper-proof time sources across distributed witness services.

Implementations are encouraged to use timestamps as informational indicators rather than security-critical values, and to corroborate timing information from multiple independent sources, such as the cryptographic event log storage services, before relying on it. When witnesses include timestamps in their proofs, using multiple witnesses with independent time sources can help detect significant clock discrepancies or manipulation attempts. Systems that detect large discrepancies in witness timestamps for the same event can flag those events for additional scrutiny. The hashlinked structure of the event log provides a partial ordering guarantee—events must have occurred in the order they appear in the chain—which are more reliable than timestamp values for determining relative event ordering. Clear documentation about the limitations of timestamp information helps prevent over-reliance on timing data that might be manipulated.

Cryptographic event logs are stored by storage services listed in the DID Document and made available during DID resolution, but the specification does not mandate a particular storage mechanism. Depending on the chosen storage approach—whether distributed ledgers, decentralized storage systems, centralized repositories, or peer-to-peer networks—different security considerations apply. If log storage is compromised, attackers might delete events to hide malicious modifications, modify historical events to change the DID document history, or deny access to legitimate log data preventing DID resolution. The integrity and availability of the storage system directly impacts the security and usability of the DID .

DID controllers are encouraged to store their cryptographic event logs with multiple independent storage services to protect against data loss and ensure availability even if one storage location fails or is compromised. The hashlinked structure and witness proofs in the log provide integrity protection, meaning that modifications to stored log data can be detected during verification, but this does not prevent deletion or denial of access. Using storage systems with built-in redundancy, access controls, and audit logging can help protect log data from unauthorized modification or deletion. For public DIDs , publishing logs to multiple publicly accessible storage services increases resilience and makes censorship more difficult. Implementations that retrieve logs are encouraged to verify the complete integrity of the log using the hashlinking and proofs, rather than trusting that stored data is authentic. Backup strategies that maintain copies of logs in geographically and operationally diverse locations can ensure long-term preservation and availability.

Each operation in the cryptographic event log contains a data integrity proof that cryptographically binds the operation to the DID document through a signature created with a verification method contained in the document. Witnesses proofs are also attached to each event in the cryptographic event log . Proper validation of these proofs is critical for security—if implementations skip proof verification or perform it incorrectly, they might accept fraudulent DID documents that were not actually created by the legitimate DID controller . The process of data integrity proof verification, which involves JSON processing, canonicalization, and signature verification, creates opportunities for implementation errors that could compromise security.

Implementations are strongly encouraged to use well-tested, standardized libraries for data integrity proof verification rather than implementing verification logic from scratch, as cryptographic implementations are prone to subtle errors that can completely compromise security. Following the verification algorithms specified in the Verifiable Credential Data Integrity 1.0 specification precisely, without shortcuts or optimizations that might skip critical validation steps, is important for maintaining security. Verification processes are encouraged to validate all aspects of the proof including the signature value, the proof purpose, the verification method reference, and any additional proof metadata. Regular testing with both valid and intentionally malformed proofs can help ensure that implementations correctly reject invalid proofs. Implementers are advised to review the security considerations in the Verifiable Credential Data Integrity 1.0 specification for additional guidance on proof verification.

The integrity of the cryptographic event log depends on each event containing a correct hash of the previous event in the previousEventHash property, creating an unbroken chain from the creation event to the most recent event. If implementations fail to properly verify that each previousEventHash hash matches the actual hash of the preceding event, or if they skip hash verification entirely, attackers could insert fraudulent events, remove events from the middle of the chain, or create alternate histories without detection. This hashlinking is fundamental to the security model—without rigorous verification, the log provides no integrity guarantees.

Implementations that verify cryptographic event logs are advised to compute the hash of each event using the same canonicalization and hashing algorithms specified in the creation and update algorithms, and verify that the computed hash matches the previousEventHash value in the following event. Verification processes are encouraged to validate the complete chain from the creation event forward without skipping any events, as gaps in verification could hide inserted or modified events. The creation event, which has no previous event, represents a trust anchor and its authenticity can be verified through witness attestations and the data integrity proof on the operation. For performance reasons, implementations might cache verification results for earlier portions of the chain, but care is needed to ensure cached results are not reused when the log has been modified. Clear error handling and reporting when hash verification fails helps diagnose attacks or data corruption issues.

The did:cel specification includes witness attestations for events but does not mandate how many witness proofs are required for an event to be considered valid or trustworthy. Different applications and trust models might require different numbers of witnesses —some might accept events with a single witness attestation, while others might require multiple witnesses . If the threshold is set too low, attackers who compromise a small number of witnesses might be able to gain a denial-of-service advantage. If set too high, legitimate operations might be blocked by witness unavailability or disagreement, creating denial-of-service conditions.

Implementations are encouraged to establish clear policies about witness proof requirements that balance security needs against operational flexibility. For high-security applications, requiring attestations from a majority or supermajority of a defined witness set provides protection against individual witness compromises. Lower-security applications might accept events with fewer attestations but implement monitoring to detect suspicious patterns. Policies can be adaptive, such as requiring more witnesses for security-critical operations like key rotations while accepting fewer witnesses for routine updates. When witnesses seem to be acting in a way that would lead to a denial of service, implementations are encouraged to investigate the discrepancy. Clear documentation about witness requirements helps DID controllers understand what level of witness attestation they need to achieve for their operations to be accepted by verifiers . Witness selection strategies that include witnesses with diverse operational and governance models can provide more robust validation than witnesses operated by related entities.

The security of DID document modifications relies on the DID controller maintaining exclusive control over the private keys corresponding to verification methods in the DID document . If an attacker gains access to these private keys through theft, social engineering, malware, or cryptographic compromise, they can create fraudulent updates to the DID document that appear legitimate because they carry valid data integrity proofs . Such unauthorized modifications might add attacker-controlled verification methods , remove legitimate verification methods, change service endpoints, or modify other DID document properties, all while appearing to be authorized changes in the cryptographic event log .

DID controllers are strongly encouraged to implement rigorous key management practices including secure generation, storage, and access control for private keys. Using hardware security modules, secure enclaves, or other tamper-resistant storage for keys that control critical DIDs can significantly reduce the risk of key theft. Regular security audits, monitoring for unexpected DID document changes, and maintaining offline backups of key material can help detect and recover from compromises. Implementing the principle of least privilege by using different verification methods for different purposes, with only minimal keys having authority to modify the DID document , can limit the impact of key compromises. When unauthorized modifications are detected, rapid key rotation following the guidance in the key rotation section can help regain control and prevent further unauthorized changes.

As cryptographic algorithms age and newer, stronger algorithms become available, DID documents might contain verification methods using different cryptographic suites with varying security strengths. An attacker might attempt to force systems to use weaker cryptographic algorithms by by exploiting verification implementations that default to weaker algorithms when multiple options are available. If successful, such downgrade attacks reduce the effective security to that of the weakest algorithm, potentially enabling signature forgeries or other cryptographic breaks that would not be possible against stronger algorithms.

Implementations are encouraged to maintain policies about which cryptographic algorithms are acceptable and to reject cryptographic event logs or proofs using algorithms that no longer provide adequate security. When DID documents contain multiple verification methods using different algorithms, verification processes are advised to require proofs using the strongest available algorithm rather than accepting weaker proofs. DID controllers are encouraged to remove deprecated verification methods using obsolete algorithms from their DID documents once stronger methods are in place, rather than maintaining weak methods for backward compatibility. Clear documentation about supported cryptographic algorithms and their expected security lifetimes helps both DID controllers and verifiers make informed decisions about algorithm selection. Following the cryptographic agility guidance in the Verifiable Credential Data Integrity 1.0 specification enables smooth transitions to newer algorithms without compromising security during migration periods.