Merge pull request #1 from aramase/3299-kms-v2

chore: add sequence diagram for encrypt and decrypt request

keps/sig-auth/3299-kms-v2-improvements/README.md

@@ -8,6 +8,9 @@
   - [Non-Goals](#non-goals)
 - [Proposal](#proposal)
 - [Design Details](#design-details)
+  - [Sequence Diagram](#sequence-diagram)
+    - [Encrypt Request](#encrypt-request)
+    - [Decrypt Request](#decrypt-request)
   - [Test Plan](#test-plan)
   - [Graduation Criteria](#graduation-criteria)
     - [Alpha](#alpha)
@@ -290,6 +293,58 @@ This `UID` field is included in the `EncryptRequest` and `DecryptRequest` of the
    2. In addition to the `UID`, the kube-apiserver will also log non-sensitive metadata such as `name`, `namespace` and `GroupVersionResource` of the object that triggered the envelope operation.
 2. Sent to the kms-plugin as part of the `EncryptRequest` and `DecryptRequest` structs.
 
+### Sequence Diagram
+
+#### Encrypt Request
+
+```mermaid
+sequenceDiagram
+    participant etcd
+    participant kubeapiserver
+    participant kmsplugin
+    participant externalkms
+    kubeapiserver->>kmsplugin: encrypt request
+    alt using key hierarchy
+        kmsplugin->>kmsplugin: encrypt DEK with local KEK
+        kmsplugin->>externalkms: encrypt local KEK with remote KEK
+        externalkms->>kmsplugin: encrypted local KEK
+        kmsplugin->>kmsplugin: cache encrypted local KEK
+        kmsplugin->>kubeapiserver: return encrypt response <br/> {"cipher": "<encrypted DEK>", currentKeyID: "<remote KEK ID>", <br/> "metadata": {"kms.kubernetes.io/local-kek": "<encrypted local KEK>"}}
+    else not using key hierarchy
+        %% current behavior
+        kmsplugin->>externalkms: encrypt DEK with remote KEK
+        externalkms->>kmsplugin: encrypted DEK
+        kmsplugin->>kubeapiserver: return encrypt response <br/> {"cipher": "<encrypted DEK>", currentKeyID: "<remote KEK ID>", "metadata": {}}
+    end
+    kubeapiserver->>etcd: store encrypt response and encrypted DEK
+```
+
+#### Decrypt Request
+
+```mermaid
+sequenceDiagram
+    participant kubeapiserver
+    participant kmsplugin
+    participant externalkms
+    %% if local KEK in metadata, then using hierarchy
+    alt encrypted local KEK is in metadata
+      kubeapiserver->>kmsplugin: decrypt request <br/> {"cipher": "<encrypted DEK>", observedKeyID: "<currentKeyID gotten as part of EncryptResponse>", <br/> "metadata": {"kms.kubernetes.io/local-kek": "<encrypted local KEK>"}}
+        alt encrypted local KEK in cache
+            kmsplugin->>kmsplugin: decrypt DEK with local KEK
+        else encrypted local KEK not in cache
+            kmsplugin->>externalkms: decrypt local KEK with remote KEK
+            externalkms->>kmsplugin: decrypted local KEK
+            kmsplugin->>kmsplugin: decrypt DEK with local KEK
+            kmsplugin->>kmsplugin: cache decrypted local KEK
+        end
+        kmsplugin->>kubeapiserver: return decrypt response <br/> {"plain": "<decrypted DEK>", currentKeyID: "<remote KEK ID>", <br/> "metadata": {"kms.kubernetes.io/local-kek": "<encrypted local KEK>"}}
+    else encrypted local KEK is not in metadata
+        kubeapiserver->>kmsplugin: decrypt request <br/> {"cipher": "<encrypted DEK>", observedKeyID: "<currentKeyID gotten as part of EncryptResponse>", <br/> "metadata": {}}
+        kmsplugin->>externalkms: decrypt DEK with remote KEK (same behavior as today)
+        externalkms->>kmsplugin: decrypted DEK
+        kmsplugin->>kubeapiserver: return decrypt response <br/> {"plain": "<decrypted DEK>", currentKeyID: "<remote KEK ID>", <br/> "metadata": {}}
+    end
+```
 
 ### Test Plan
 

keps/sig-auth/3299-kms-v2-improvements/kep.yaml

@@ -2,7 +2,7 @@ title: KMS v2 Improvements
 kep-number: 3299
 authors:
   - "@ritazh"
-  - "aramase"
+  - "@aramase"
 owning-sig: sig-auth
 participating-sigs:
   - sig-auth