add description for key update.

Signed-off-by: Jiewen Yao <[email protected]>

specification/07-theory_operations.adoc

@@ -876,6 +876,37 @@ TVM ->> TVM: Use device interface
 
 === Interface Unbinding
 
+=== Session Key Update
+
+In TEE-IO architecture, there are 2 sessions established between the host TSM
+and the device: SPDM session and IDE session. Both sessions use AES-GCM-256
+keys to protect the data. As such, the host software needs to update the
+session keys before the use of keys reach to the limit.
+
+==== SPDM Session Key Update
+
+SPDM session key update is managed by SPDM KEY_UPDATE command.
+The TSM shall count the usage of SPDM session keys, also knowns as the 64bit
+`sequence number` defined in <<SecuredSPDM>>.
+Whenever the VMM asks the TSM to encrypt the SPDM message, the TSM shall check
+if the `sequence number` reaches to the limit. If yes, the TSM shall notify VMM to
+perform SPDM Key Update action (through the `sbi_covh_spdm_key_update()` `COVH` call).
+
+==== IDE Session Key Refresh
+
+IDE session key refresh is managed by host software via IDE_KM command.
+The host root port IDE engine shall count the 64bit invocation field of the IV,
+and check if the value reaches to the limit, then it process the IDE TLP.
+If overflow happens, the IDE stream shall be in insecure state.
+In order to keep the IDE session alive, the VMM should perform IDE Key Refresh
+action (through the `sbi_covh_ide_key_refresh()` `COVH` call) before the IDE
+session reaches the limit of the key usage.
+
+Currently, there is no robust way to get the invocation field of IV for a given
+IDE session. One possible way is to do time-based refresh. For example, the VMM
+perform the IDE key refresh every several minutes based on the calculation of
+maximum usage of IDE TLP.
+
 === Device and Interface Lifecycle
 
 When combined together, the flows and ABIs described in the previous sections

specification/09-coveio_abi.adoc

@@ -270,6 +270,47 @@ The possible error codes returned in `sbiret.error` are shown below.
 | SBI_ERR_FAILED          | The operation failed for unknown reasons.
 |===
 
+[#sbi_covh_spdm_key_update]
+===== Function: CoVE Host SPDM Key Update (FID #1033)
+[source, C]
+-----
+struct sbiret sbi_covh_spdm_key_update()(unsigned long device_id);
+-----
+
+Perform SPDM key update for a device.
+
+The possible error codes returned in `sbiret.error` are shown below.
+
+[#table_sbi_covh_spdm_key_update]
+.CoVE Host SPDM Key Update
+[cols="2,3", width=90%, align="center", options="header"]
+|===
+| Error code              | Description
+| SBI_SUCCESS             | The operation completed successfully.
+| SBI_ERR_FAILED          | The operation failed for unknown reasons.
+|===
+
+[#sbi_covh_ide_key_refresh]
+===== Function: CoVE Host IDE Key Refresh (FID #1034)
+[source, C]
+-----
+struct sbiret sbi_covh_ide_key_refresh()(unsigned long device_id,
+                                         unsigned long stream_id);
+-----
+
+Perform IDE key refresh for a stream on a device.
+
+The possible error codes returned in `sbiret.error` are shown below.
+
+[#table_sbi_covh_ide_key_refresh]
+.CoVE Host IDE Key Refresh
+[cols="2,3", width=90%, align="center", options="header"]
+|===
+| Error code              | Description
+| SBI_SUCCESS             | The operation completed successfully.
+| SBI_ERR_FAILED          | The operation failed for unknown reasons.
+|===
+
 === CoVE IO Guest Extension (EID #0x434F5647 "COVG")
 
 ==== Physical Device Query