DIDComm Guidebook

If you're a developer who wants to learn the practicalities of DIDComm -- getting started, common recipes, libraries and tools, the theory behind the spec, or how your peers are solving interesting problems -- this is the place.

This is a living doc, updated and expanded regularly by the DIDComm User Group. If you have suggestions for the book, we welcome your contributions; reach out to us on Discord or email for help.

This version of the book focuses on DIDComm v2 (the one incubated by DIF, finalized in early 2022). For info about migration from DIDComm v1, see Appendix: Migration from DIDComm v1. A new version of DIDComm, v3, is imagined. This would be an IETF standard that builds on v2 with a session construct, improved binary support, leaner messages for IoT, and so forth. When we have links for that work, we'll add them here.

Contents

  1. Why DIDComm?
  2. Hello World
    1. Choosing libraries and tools
    2. Putting a message in an encrypted envelope
    3. Using a transport
    4. Receiving a message
  3. Threading
  4. Protocols
    1. Implementing a protocol
    2. Designing your own protocol
      1. When this makes sense
      2. Conventions
      3. Best practices
    3. Sharing your protocol
    4. Co-protocols
  5. Recipes
    1. Debugging
    2. Timeouts
    3. Retries
    4. Localization
    5. N-wise
    6. Bootstrapping
    7. Using DIDComm security outside DIDComm
  6. Safety
    1. Privacy
    2. Security
      1. Authcrypt vs. Anoncrypt
      2. Choosing curves
      3. Choosing DID methods
    3. Message security contexts
    4. DID rotation
    5. Perfect forward secrecy
    6. Man in the middle
  7. Routing
  8. Appendix:
  9. Appendix: Migration from DIDComm v1
    1. What's new
    2. Migrator script