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