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