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 #pii key to verificationMethod

Add your own P-256 public key to verificationMethod with an id ending in #pii, the type JsonWebKey2020 and the key in publicKeyJwk, and reference it in keyAgreement. The keys Notabene generated stay in the document, and Notabene encrypts the PII you receive to your #pii key as soon as it is there. The Add your own #pii key recipe does this for you.

• 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"
      },
      {
        "id": "did:web:vasps.id:cryptoVASP#x25519-agreement-key",
        "type": "X25519KeyAgreementKey2019",
        "controller": "did:web:vasps.id:cryptoVASP",
        "publicKeyBase58": "JhNWeSVLMYccCk7iopQW4guaSJTojqpMEELgSLhKwRYJ"
      },
      {
        "id": "did:web:vasps.id:cryptoVASP#notabene-pii",
        "type": "JsonWebKey2020",
        "controller": "did:web:vasps.id:cryptoVASP",
        "publicKeyJwk": {
          "kty": "EC",
          "crv": "P-256",
          "x": "OWyK2OK-H35VEYcH758MZ_R2wzFpn4Th3oEvqZh_AvI",
          "y": "GbgUDbrO7Wucdx64EA8SGQbVAi6cUHYZ-g2zI9BcoH4"
        }
      },
      {		//add your own P-256 key here. Make sure the "type" is JsonWebKey2020 and the "id" ends with #pii:
        "id": "did:web:vasps.id:cryptoVASP#pii",
        "type": "JsonWebKey2020",
        "controller": "did:web:vasps.id:cryptoVASP",
        "publicKeyJwk": {
          "kty": "EC",
          "crv": "P-256",
          "x": "6xMrKpAWBOEyfUNkQAXEB93g5DErVMjhjhxznxo4V1k",
          "y": "zHuZLqpUZf6t1H2i1sTb455ywWNZBru3KrcefjRwzMA"
        }
      }
  ],
  ...
  //etc.
  ...
    "keyAgreement": [
      "did:web:vasps.id:cryptoVASP#x25519-agreement-key",
      "did:web:vasps.id:cryptoVASP#notabene-pii",
      "did:web:vasps.id:cryptoVASP#pii" //reference your own key here
    ],
  ...
  //etc.
  

Deprecated key type

Earlier versions of this page and the deprecated Create E2E keys and DIDdoc recipe published the #pii key with the type EcdsaSecp256r1VerificationKey2019, which is deprecated. Notabene ignores a #pii key of this type, so the PII you receive is encrypted to a key Notabene holds and Notabene can still decrypt it.

If your DID document has this entry, change type to JsonWebKey2020 and publish the same public key in publicKeyJwk. Your key pair stays the same, and Notabene switches to it within 5 minutes.

// deprecated
{
  "id": "did:web:vasps.id:cryptoVASP#pii",
  "type": "EcdsaSecp256r1VerificationKey2019",
  "controller": "did:web:vasps.id:cryptoVASP",
  "publicKeyHex": "03a34b99f22c790c4e36b2b3c2c35a36db06226e41c692fc82b8b56ac1c540c5bd"
}