1# VMI Certificate Exchange
2
3Author: Raviteja Bailapudi
4
5Other contributors: Ratan Gupta
6
7Created: 07/10/2019
8
9## Glossary
10
11- HMC - Hardware Management Console : Management console for IBM enterprise
12  servers.
13- PHYP - Power Hypervisor : This orchestrates and manages system virtualization.
14- VMI - Virtual Management Interface : The interface facilitating communications
15  between HMC and PHYP embedded linux virtual machine.
16- KVM - Kernel Virtual Machine : Open source virtualization software
17
18## Problem Description
19
20On enterprise POWER systems, the Hardware management console (HMC) needs to
21establish a secure connection to the Virtualization management interface (VMI)
22for virtualization management.
23
24VMI is an embedded Linux VM created and run on PHYP which provides the
25virtualization function.
26
27HMC requires client key, client.crt, and CA.crt to establish secure connection
28to VMI.
29
30BMC needs to provide certificate exchange functionality to management console
31due to following reasons:
32
33- Host firmware (PHYP) does not have authentication mechanism.
34- VMI trusts that BMC has authenticated and verified the authenticity of any
35  client connected as there is a secure authenticated connection already exists
36  between HMC and BMC.
37
38Management console needs an API through which it can send the CSR to VMI (CA)
39and gets the signed certificate and the CA certificate from VMI. This design
40will describe how certificates get exchanged between management console and VMI
41
42IBM systems can run both IBM specific host-firmware (PHYP) and Linux KVM. This
43API would be used only for the PHYP based machines.
44
45Enable and disable of this API would be controlled by the build time
46configurable variable.
47
48## Background and References
49
50- VMI will be created and run on PHYP that will provide the virtualization
51  function.
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.
58
59## Requirements
60
61BMC will provide an interface for management console to exchange certificate
62information from VMI so that HMC can establish secure connection to VMI.
63
64## Proposed Design
65
66The management console can send CSR string to VMI (CA) and get signed
67certificate and Root CA certificate via proposed BMC interface.
68
69In this interface perspective, the HTTP error code could be 4XX/5XX. It would be
70mapped depending on the PLDM error response.
71
72HMC can query BMC state and use this API to initiate certificate exchange.If HMC
73runs this command before PHYP boots, PLDM command returns error If PLDM command
74throws an error, that would be mapped to Internal server Error (500).
75
76### Design Flow
77
78```ascii
79    +------------+        +--------+            +--------+
80    |    HMC     |        |  BMC   |            |  VMI   |
81    |  (client)  |        |        |            |  (CA)  |
82    +-----+------+        +----+---+            +---+----+
83          |                    |                    |
84          |                    |                    |
85          +------------------->+                    |
86          | VMI Network info   |                    |
87          +<-------------------+                    |
88          |                    |                    |
89client.key|                    |                    |
90client.csr     SignCSR()       | pldm call to host  |
91          +------------------->+------------------->|
92          |                    |                    |  Sign CSR
93          | SignCSR() response | pldm response from host
94          +<-------------------+<-------------------|
95          |                    |                    |
96  Client.crt                   |                    |
97  CA.crt                       |                    |
98          |                    |                    |
99          |                    |                    |
100          |                    |                    |
101          |                    |                    |
102          +                    +                    +
103
104```
105
106### VMI certificate exchange
107
108Management console should use the below REST commands to exchange certificates
109with VMI
110
111#### Get Signed certificate:
112
113REST command to get signed client certificate from VMI
114
115Request:
116
117```bash
118curl -k -H "X-Auth-Token:  <token>" -X POST "Content-Type: application/json" -d
119  '{"CsrString":"<CSR string>"}' https://{BMC_IP}/ibm/v1/Host/Actions/SignCSR
120```
121
122Response: This will return the certificate string which contains signed client
123certificate
124
125```
126 {
127   “Certificate”: "<certificate string>"
128 }
129
130```
131
132#### Get Root certificate:
133
134REST command to get VMI root certificate
135
136Request:
137
138```bash
139curl -k -H "X-Auth-Token:  <token>" -X GET http://{BMC_IP}/ibm/v1/Host/Certificate/root
140```
141
142Response: This will return the certificate string which contains and root CA
143certificate.
144
145```
146 {
147   “Certificate”: "<certificate string>"
148 }
149
150```
151
152This interface returns HTTP error codes 5XX/4XX in failure cases
153
154## Alternatives considered:
155
156Have gone through existing BMC certificate management infrastructure if we can
157extend for this use case.
158
159### Current flow for generating and installing Certificates (CSR Based):
160
161- Certificate Signing Request CSR is a message sent from an applicant to a
162  certificate authority in order to apply for a digital identity certificate.
163- The user calls CSR interface BMC creates new private key and CSR Certificate
164  File
165- CSR certificate is passed onto the CA to sign the certificate and then upload
166  CSR signed certificate and install the certificate.
167
168### Note
169
170- Our existing BMC certificate manager/service have interfaces to generate CSR,
171  upload certificates and other interfaces to manage
172  certificates(replace,delete..etc).
173- In VMI certificate exchange, requirement for BMC is to provide an interface
174  for management console to get CSR certificate signed by VMI (CA).
175- We don’t have any existing certificate manager interface to forward CSR
176  request to CA to get signed by CA.
177- Here proposal is to have SignCSR() interface which accepts CSR string and
178  return signed certificate and Root CA certificate.
179- This requirement is out of scope for existing certificate manager so proposing
180  SignCSR interface as management console specific interface.
181
182### Alternate Design
183
184```ascii
185    +------------+        +--------+            +--------+
186    |    HMC     |        |  BMC   |            |  VMI   |
187    |  (client)  |        |        |            |  PHYP  |
188    +-----+------+        +----+---+            +---+----+
189          |                    |                    |
190          |                    |                    |
191          +------------------->+                    |
192          | VMI Network info   |                    |
193          +<-------------------+                    |
194          |                                         |
195          |                SSL tunnel               |
196          +---------------------------------------->|
197          |              Verify Password            |Nets
198          +---------------------------------------->|
199          |                                         |
200          |                  pldm                   |pldm call to authenticate
201          +<-------------------+<-------------------|
202          |                    |                    |
203          |                   pam                   |
204          |              authentication             |
205          |                    +------------------->|
206          |                                         |
207          |        session established              |
208          |<--------------------------------------->|
209
210```
211
212- In this alternate design, Management console establishes connection to VMI and
213  sends Verify Password command to authenticate user to establish secure
214  session.
215- VMI does not have authentication method, so VMI needs to use BMC
216  authentication method over PLDM.
217- There are security concerns if raw password is getting sent over PLDM in clear
218  text over LPC, so this design ruled out.
219
220## Impacts
221
222- Create new interface GetRootCertificate in webserver which reads root
223  certificate from '/var/lib/bmcweb/RootCert' file.This API can handle muptiple
224  requests at the sametime.
225- PLDM gets root certificate as soon as VMI boots and it writes to
226  '/var/lib/bmcweb/RootCert'.
227- Implement D-Bus interface to create dbus object for each signCSR so that
228  multiple requests can work at the sametime. D-bus service:
229  xyz.openbmc_project.Certs.ca.authority.Manager Object path :
230  /xyz/openbmc_project/certs/ca Interface : xyz.openbmc_project.Certs.Authority
231  Method : SignCSR
232- Dbus object contains CSR,ClientCertificate and Status properties.
233- PLDM looks for interface added signal for each object created and reads CSR
234  property for CSR string and forwards this CSR string to VMI for signing this
235  CSR.
236- Once PLDM on BMC gets the client certificate from VMI, it updates the
237  ClientCertificate D-bus property and updates the Status property to Complete
238  in the Dbus object.
239- Create new interface SignCSR in webserver which takes CSR string as input and
240  returns certificate string.This interface calls SignCSR dbus method and looks
241  for Status property changed signal to verify status.Reads ClientCertificate
242  property content and return certificate string.
243- On completion of serving the sign CSR request, respective dbus object will be
244  deleted before returning certificate string to client.
245- BMC is passthrough which allows certificate exchange between VMI and HMC. BMC
246  does not store or parse these certificates.
247- Build time configure variable defined to control enable and disable of this
248  API in webserver. It is required only for IBM systems with IBM specific
249  host-firmware (PHYP)
250
251## Testing
252
253- Test the interface command from a management console and verify if certificate
254  exchange worked as expected and verify if management console able to establish
255  secure connection to VMI.
256
257- Certificate exchange fails in the following scenarios
258
259  - If PHYP is not up
260  - If PHYP throws error for certificate validation. This interface returns
261    appropriate HTTP error code (4XX/5XX) based on type of error.
262
263- If there are issues like certificate expiry, revocation, incorrect date/time
264  and incorrect certificates, then HMC fails to establish connection to VMI.
265