# DKMS demo use case

## Scenario
1. As a government institution, I want to issue birth certificate with name, surname and parents names/surnames, so that the newborn gets registered in the country of birth.
2. As a newborn parent I want to receive the birth certificate so that I can proof parenthood to other insitutions if needed.

## Tech details

### Infrastructure to be set
- 3 witnesses instances
- 2 watcher instance
- government institution issuer via client using Node.JS bindings (either accessible via terminal or some simple WEB, but the former is preferred).
- some individual that gets the birth certificate attestation via Android app (TDA) using Dart bindings.

Note `N=2F+1` instances for witnesses satisfies all cases for witnesses, where F witnesses might be faulty (or dishonest). However, the controller itself may also be faulty (dishonest) as it can be exploited. To satisfy not only F dishonest witnesses, but also dishonest (exploited) controller, we need `N = 3F + 1` nodes. This equation also satisfies Byzantine Fault Tolerance (BFT).
If interested, the original paper of Byzantine Faults https://lamport.azurewebsites.net/pubs/byz.pdf describes this problem by analogy to Commander (we have Controllers) and Lieutenants (we have Witnesses).

### Demo step by step from the DKMS perspective

1. We have 3 witnesses, 1 watcher and 2 controllers established. We assume federated use case, where amount of witnesses is constrained. Witnesses know each other and there is no discovery mechanism required.
3. Controllers do not have any relationship with Watcher established. To establish the relationship, a third party mechanism is used (QR code scan for example). Getting the Watcher OOBI essentially allows the Controller to discover where the Watcher is. Once Watcher is discovered, Controller "delegates" this Watcher (by issuing an OOBI) to be Controller's Watcher.
Controller then sends this OOBI to Watcher as a proof of watcher establishment and primarily as a Controller authentication mechanism from the Watcher perspective.
5. An individual controller (1st controller) establishes a relationship with government institution controller (2nd controller) indirectly by doing OOBI discovery of the 1st controller Witness OOBI (QR containing OOBI of 1st controller Witness).
4. Established Controllers do know Witness OOBI's, hence they're able to use them when they bootstrap their Identifiers. Watcher on the other side do not know Witnesses. They need to be discovered first.
7. 1st Controller (the holder) needs to assure the end-verifiability of 2nd controller (the issuer) DKMS idenfiter. In order to do so, she asks her Watcher whether she knows the 1st controller identifier. Apparently Watcher doesn't know yet the 2nd controller identifier. However, since 1st controller does know 2nd controller OOBI, she passes this OOBI to her Watcher, so the Watcher is able to conduct the whole discovery. What watcher do here:
1. The OOBI that watcher gets from 1st controller contains OOBI's of all the witnesses of 2nd controller.
2. Because watcher doesnt know the identifier yet, she asks random witness from OOBI about 2nd controller identifier. If witness would not respond, watcher would have ask next one.
3. Randomly selected witness responds with 2nd controller KERL and KEL.
4. Watcher performs all types of validation upon received data, including KEL integrity, KERL integrity and finally that the KEL is indeed fully witnessed (the requested amount of receipts for each KEL event is satisfied; note this param is configurable for each identifier).
5. Watcher is now "watching" 2nd controller identifier that is fully witnessed.
6. 1st controller gets the 2nd controller identifier KEL and KERL.
8. First controller issues an application to second controller (this is assumed and is not part of the demo) and upon that application second controller issues the birth certificate as ACDC cred.
9. As soon as 2nd controller issued the ACDC, she rotates the keys to next ones. (case for demo purposes, that is also not the case in real use cases)
10. First controller somehow (maybe even by copy-paste, as the purpose of this demo is to demonstrate DKMS, not TDA's comm) gets the ACDC and:
1. is able to preview it (OCA preview).
2. is able to perform the end-verifiability of this ACDC. What controller do:
1. 1st controller deserializes the ACDC so that it becomes ready for further processing.
2. 1st controller tries to verify the ACDC signature against the 2nd controller keys from KEL, but apparently discovers that it does not verify (note there was a rotation event in previous steps).
3. 1st controller tries to ensure she has the newest version of 2nd controller KEL. She asks his watcher, but due to lack of communication between watchers and witnesses for updates, the watcher needs to manually trigger the request and send `qry` msg to random witness.
4. Watcher discovers that the `rpy` message she received from witness contains different `ksn` message as a `rpy` message body. This means the KEL is stale and needs to be refreshed. Watcher queries for new changes.
5. Watcher pushes missing rotation event to 1st controller.
6. 1st controller successfully verifies ACDC.