Merge branch 'wg4-flowcharts-updates' into 'wg4'

Wg4 flowcharts updates

See merge request !11

README.md

@@ -2,7 +2,7 @@
 
 This is a prototypically Key Management System (KMS) for Quantum Key Distribution Networks (QKDN).
 
-It uses, by now, an emulation of a quantum link to exchange random numbers between neighboring quantum network elements.
+It uses, by now, an emulation of a quantum link to exchange random numbers between neighboring, i.e., directly attached, quantum network elements.
 
 **Note well** _This is not intended to be used in production environments, neither in networks that can be reached by everybody, nor in other uncontrolled settings._
 
@@ -21,9 +21,9 @@ The DemoQuanDT project is funded by the german ministry of education and researc
 #### Overview 
 The generation of random numbers is done via the golang's [crypto/rand](https://pkg.go.dev/crypto/rand) pseudo random number generator (PRNG). The sending quantum network element takes the generated random numbers and sends them by means of an UDP datagram to the receiving quantum network element. The receiver can take these random numbers and hand them over to the KMS for further processing.
 
-The quantum network element is integrated with the proto-kms, in case of this PRNG-based emulation. 
+In case of this PRNG-based emulation, the quantum network element is integrated with the proto-kms. 
 
-The KMS receives an amount or random numbers from the quantum layer, whereas the actual amount will vary over time.
+The KMS receives an amount or random numbers (called bulk keys) from the quantum layer, whereas the actual amount will vary over time.
 
 #### Generation of Random Numbers
 
@@ -38,15 +38,24 @@ First, rand is used to generate the amount of random numbers `numRands`and then
 
 A quantum layer link peer is the communication partner on a point-to-point link. One has to generate a new peer in the quantum layer in order to communicate with the peer. 
 
+#### Beyond Pseudo Random Number Generator (PRNG) based Emulation
+
+Future versions of the quantum layer may include implementations of emulations of real quantum links. 
+
 # Interfaces to the proto-kms
 
 ## Interface to the Quantum Layer
 
-This interface is solely a go API within the proto-kms. 
+This interface is solely a go API within the proto-kms and is accessible here [quantumlayer/quantumlayer.go](quantumlayer/quantumlayer.go) as the interface definitions.
 
 ## Inter-KMS Communication
 
-This interface is required for the communication between the peering KMS in order to coordinate their actions for key selection and key forwardwing path configuration. This is in *interkmsproto*.
+This interface is required for the communication between the peering KMS in order to coordinate their actions for key selection and key forwardwing path configuration. This is in [api/kmsintercom/kmsintercom/kmsintercom.proto](api/kmsintercom/kmsintercom/kmsintercom.proto)
+
+## Interface between KMS and SDN-Controller
+
+While there are standards for the communication between an SDN-controller and a KMS (see section *ETSI-Interfaces* below), we are currently experimenting with our interfaces between both entities. The currently implemented protocol flow can be found in the section *Protocol Flow Charts in Use*.
+
 
 ## ETSI-Interfaces 
 
@@ -54,32 +63,62 @@ There are basically two ETSI interfaces, i.e.,
  - ETSI QKD GS 14 for retrieval of keys by an external entity from the kms
  - ETSI QKD GS 15 for the configuration of the key forwarding process and peers of the kms
 
- However, at this point of this, both interfaces are lumped together in one gRPC interface *kmsetsiproto*.
+By now both are not supported. Please look instead in the above section *Interface between KMS and SDN-Controller*.
 
-### Encryption Key Retrieval Interface
 
-### SDN Controller (ETSI GS QKD 15)
+# Protocol Flow Charts in Use
 
+This section docucments the current flow charts implemented. 
 
-# Interactions (AKA Flowcharts)
+## GRPC Variant for Configuration of Forwarding
+
+This solely depicts the process for KMS1, but omits the to-be-done process for KMS2.
 
 ```mermaid 
 sequenceDiagram
 QKDNC->>KMS1: ETSIGetQuantumInterfaces()
-loop 
-    KMS1->>KMS1: range es.handlingEkms.QuantumElements
-end
 KMS1-->>QKDNC: List QuantumInterfaces
-QKDNC->>KMS1: ETSIAddKMSPeer(KMS2)
+QKDNC->>KMS1: ETSIAddKMSPeer(QuantumInterface, KMS2, ListOptions...)
+KMS1->>KMS2: InterComCapabilities(Supported_KeyChopLenghts)
+KMS2->>KMS1: InterComCapabilitiesReply(Agreed_KeyChopLenght)
 KMS1-->>QKDNC: KMSPeer added
-KMS1->>KMS2: InterComCapabilities()
-KMS2->>KMS1: InterComCapabilitiesReply
-QKDNC->>KMS1: AddSession() NOTIMPLYET
-KMS1->>KMS2: InterComKeyTransportSessionHandling()
-KMS2->>KMS1: InterComKeyTransportSessionHandlingReply
-KMS1-->>QKDNC: SessionReply NOTIMPLYET
+QKDNC->>KMS1: AssignForwarding(PathID, PreviousHop, NextHop) 
+KMS1-->>QKDNC: AssignForwardingReply
+```
+
+## (Intended) gNMI/YANG Variant for Configuration of Forwarding
 
+This solely depicts the process for KMS1, but omits the to-be-done process for KMS2.
+
+```mermaid 
+sequenceDiagram
+QKDNC->>KMS1: ETSIGetQuantumInterfaces()
+KMS1-->>QKDNC: List QuantumInterfaces
+QKDNC->>KMS1: Yang_AddKMSPeer(QuantumInterface, KMS2, ListOptions...)
+KMS1-->>QKDNC: gnmi_OK
+QKDNC->>KMS1: gnmi_Subscribe(KMS2_Peer_Status)
+KMS1-->>QKDNC: gnmi_Subscribe_OK
+KMS1->>KMS2: InterComCapabilities(Supported_KeyChopLenghts)
+KMS2-->>KMS1: InterComCapabilitiesReply(Agreed_KeyChopLenght)
+KMS1->>QKDNC: gnmi_Subscribe_Update(KMS2_Peer_Status)
+QKDNC->>KMS1: Yang_GetPeerInfo(KMS2)
+KMS1-->>QKDNC: gnmi_OK
+QKDNC->>KMS1: Yang_AssignForwarding(PathID, PreviousHop, NextHop) 
+KMS1-->>QKDNC: gnmi_OK
 ```
 
+## Forwarding
+
+The flow with one intermediate KMS (i.e., KMS2). This is omitting the request to forward the payload. 
+
+```mermaid 
+sequenceDiagram
+KMS1->>KMS2: KeyForwardingRequest(PathID, OTP_encrypted(Payload))
+KMS2-->>KMS1: KeyForwardingResponse
+KMS2->>KMS3: KeyForwardingRequest(PathID, OTP_encrypted(Payload))
+KMS3-->>KMS2: KeyForwardingResponse
+
 
 
+```
+