designs/management-console/VMI_Certificate_Exchange.md

11 - HMC - Hardware Management Console : Management console for IBM enterprise
13 - PHYP - Power Hypervisor : This orchestrates and manages system virtualization.
14 - VMI - Virtual Management Interface : The interface facilitating communications
16 - KVM - Kernel Virtual Machine : Open source virtualization software
20 On enterprise POWER systems, the Hardware management console (HMC) needs to
21 establish a secure connection to the Virtualization management interface (VMI)
22 for virtualization management.
30 BMC needs to provide certificate exchange functionality to management console
33 - Host firmware (PHYP) does not have authentication mechanism.
34 - VMI trusts that BMC has authenticated and verified the authenticity of any
38 Management console needs an API through which it can send the CSR to VMI (CA)
40 will describe how certificates get exchanged between management console and VMI
42 IBM systems can run both IBM specific host-firmware (PHYP) and Linux KVM. This
50 - VMI will be created and run on PHYP that will provide the virtualization
52 - When the VMI is powered on it generates a public-private key pair and a
53   self-signed root certificate is created using this key pair.
54 - VMI acts as root CA only for VMI endpoints, its not an official CA and uses
55   its self-signed certificate to sign CSR from client.
56 - HMC needs to establish secure connection to VMI to perform virtualization
57   management.
61 BMC will provide an interface for management console to exchange certificate
66 The management console can send CSR string to VMI (CA) and get signed
79     +------------+        +--------+            +--------+
82     +-----+------+        +----+---+            +---+----+
85           +------------------->+                    |
87           +<-------------------+                    |
91           +------------------->+------------------->|
94           +<-------------------+<-------------------|
108 Management console should use the below REST commands to exchange certificates
118 curl -k -H "X-Auth-Token:  <token>" -X POST "Content-Type: application/json" -d
138 curl -k -H "X-Auth-Token:  <token>" -X GET http://{BMC_IP}/ibm/v1/Host/Certificate/root
154 Have gone through existing BMC certificate management infrastructure if we can
159 - Certificate Signing Request CSR is a message sent from an applicant to a
161 - The user calls CSR interface BMC creates new private key and CSR Certificate
163 - CSR certificate is passed onto the CA to sign the certificate and then upload
168 - Our existing BMC certificate manager/service have interfaces to generate CSR,
171 - In VMI certificate exchange, requirement for BMC is to provide an interface
172   for management console to get CSR certificate signed by VMI (CA).
173 - We don’t have any existing certificate manager interface to forward CSR
175 - Here proposal is to have SignCSR() interface which accepts CSR string and
177 - This requirement is out of scope for existing certificate manager so proposing
178   SignCSR interface as management console specific interface.
183     +------------+        +--------+            +--------+
186     +-----+------+        +----+---+            +---+----+
189           +------------------->+                    |
191           +<-------------------+                    |
194           +---------------------------------------->|
196           +---------------------------------------->|
199           +<-------------------+<-------------------|
203           |                    +------------------->|
206           |<--------------------------------------->|
210 - In this alternate design, Management console establishes connection to VMI and
211   sends Verify Password command to authenticate user to establish secure
213 - VMI does not have authentication method, so VMI needs to use BMC
215 - There are security concerns if raw password is getting sent over PLDM in clear
220 - Create new interface GetRootCertificate in webserver which reads root
223 - PLDM gets root certificate as soon as VMI boots and it writes to
225 - Implement D-Bus interface to create dbus object for each signCSR so that
226   multiple requests can work at the sametime. D-bus service:
230 - Dbus object contains CSR,ClientCertificate and Status properties.
231 - PLDM looks for interface added signal for each object created and reads CSR
234 - Once PLDM on BMC gets the client certificate from VMI, it updates the
235   ClientCertificate D-bus property and updates the Status property to Complete
237 - Create new interface SignCSR in webserver which takes CSR string as input and
241 - On completion of serving the sign CSR request, respective dbus object will be
243 - BMC is passthrough which allows certificate exchange between VMI and HMC. BMC
245 - Build time configure variable defined to control enable and disable of this
247   host-firmware (PHYP)
251 - Test the interface command from a management console and verify if certificate
252   exchange worked as expected and verify if management console able to establish
255 - Certificate exchange fails in the following scenarios
256   - If PHYP is not up
257   - If PHYP throws error for certificate validation. This interface returns
260 - If there are issues like certificate expiry, revocation, incorrect date/time