Key Management in DIDdocs

Outgoing data: You can choose (in Settings) to encrypt PII data yourselves. In such case you, your system, will post encrypted IVMS payloads to a dedicated endpoint (/presentation), not to a DIDComm endpoint directly but to the Notabene platform API. The platform will take care applying message level encryption and signing, and further routing to the DIDComm endpoint of the requester/receiver (when your policies allow). Therefore there is no need for signing of the PII data, only for encryption, using the counterparty pubkey as listed in their DIDDoc. Notabene will, via webhooks, tell you to which keys to encrypt what data. More info on that later.

💡The point is: there is no need to add additional signature/authentication keys.

Incoming data: When you also choose to receive the encrypted PII data yourselves and don’t want Notabene to be able to decrypt on your behalf, you can add your PII keys to the DIDDoc.

To accommodate special-purpose keys for encrypting personally identifiable information (PII) data while still allowing for standard encryption and signing of other DIDComm messages, we use PII keys and indicate their purpose in the key ID. Our chosen approach is to introduce a #PII extension to the key agreement "id" in the DIDDoc. This key ID extension clarifies which of the public keys is designated for PII encryption, separate from the standard keyAgreement used for general communication. When you use the #PII extension in the key ID, the Notabene platform will add the pubkey to webhooks. For outgoing PII, we add the receivers dedicated PII key, for incoming data, we add the sender’s PII key to the webhooks. This allows your system to encrypt/decrypt without the need to lookup the counterparty DIDDoc.

Adding a #PIIextension to the Keys in verificationMethod

In this approach, you could simply update the hosted #PII key entry in the verificationMethod to include your own instead.

• Example DIDDoc entry (only showing the sections to update)

  JSON

  ...
  // starting from:
  "verificationMethod": [
      {
        "id": "did:web:vasps.id:cryptoVASP#ed25519-signing-key",
        "type": "Ed25519VerificationKey2018",
        "controller": "did:web:vasps.id:cryptoVASP",
        "publicKeyBase58": "H3C2AVvLMv6gmMNam3uVAjZpfkcJCwDwnZn6z3wXmqPV",
        "publicKeyHex": "de9edb7d7b7dc1d4d35b61d1dbf26e85c1b29cc6d7dc3e0a8b9f5b1b1e7b7b1a"
      },
      {
        "id": "did:web:vasps.id:cryptoVASP#x25519-agreement-key",
        "type": "X25519KeyAgreementKey2019",
        "controller": "did:web:vasps.id:cryptoVASP",
        "publicKeyBase58": "JhNWeSVLMYccCk7iopQW4guaSJTojqpMEELgSLhKwRYJ",
        "publicKeyHex": "d2f6b3e1c8a7d9e4f2c1b8e7a6d3c9f2e1c8a7d6b3e9f4c2a1d8e7b6c3f9e2d1"
      },
    {		//update this key with your own EcdsaSecp256r1VerificationKey2019. Make sure the "id" ends with #pii: 
        "id": "did:web:vasps.id:cryptoVASP#pii",
        "type": "EcdsaSecp256r1VerificationKey2019",
        "controller": "did:web:vasps.id:cryptoVASP",
        "publicKeyHex": "03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd"
      }
  ],
  ...
  //etc.
  ...
    "keyAgreement": [
      "did:web:vasps.id:cryptoVASP#x25519-agreement-key",
      "did:web:vasps.id:cryptoVASP#pii" //update the id reference here (in case you updated the "id" of the PII key)
    ],
  ...
  //etc.