1# BMC Certificate management
2
3## Overview
4
5Certificate management allows to replace the existing certificate and private
6key file with another (possibly certification Authority (CA) signed) certificate
7and private key file. Certificate management allows the user to install both the
8server and client certificates. The REST interface allows to update the
9certificate, using an unencrypted certificate and private key file in .pem
10format, which includes both private key and signed certificate.
11
12### Signed Certificate upload Design flow(Pre-generated)
13
14- The REST Server copies the certificate and private key file to a temporary
15  location.
16- REST server should map the URI to the target DBus application (Certs) object.
17  The recommendation for the D-Bus application implementing certificate D-Bus
18  objects is to use the same path structure as the REST endpoint. e.g.:
19  - The URI /xyz/openbmc_project/certs/server/https maps to instance of the
20    certificate application handling Https server certificate.
21  - The URI /xyz/openbmc_project/certs/client/ldap maps to instance of the
22    certificate application handling LDAP client certificate.
23  - The URI /xyz/openbmc_project/certs/authority/truststore maps to instance of
24    the certificate application handling Certificate Authority certificates.
25- REST server should call the install method of the certificate application
26  instance.
27- Certificate manager application also implements d-bus object
28  xyz.openbmc_project.Certs.Manager. This includes the collection of
29  "certificates specific d-bus objects" installed in the system. This d-bus
30  provide option to view the certificate on PEM format and delete the same.
31  Refer [Wikipedia][privacy-enhanced-mail] for details.
32- Applications should subscribe the xyz.openbmc_project.Certs.Manager to see any
33  new certificate is uploaded or change in the existing certificates.
34- Certificate manager scope is limited to manage the certificate and impacted
35  application is responsible for application specific changes.
36- In case of delete action, certificate manager creates a new self signed
37  certificate after successful delete (regards only server type certificates)
38
39[privacy-enhanced-mail]: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
40
41### REST interface
42
43```plain
44url: /xyz/openbmc_project/certs/server/https
45Description: Update https server signed certificate and the private key.
46Method: PUT
47
48url: /xyz/openbmc_project/certs/server/https/<cert_id>
49Description: Delete https server signed certificate and the private key.
50Method: DELETE
51
52url: /xyz/openbmc_project/certs/client/ldap
53Description: Update ldap client certificate and the private key.
54Method: PUT
55
56url: /xyz/openbmc_project/certs/client/ldap/<cert_id>
57Description: Delete ldap client certificate and the private key.
58Method: DELETE
59
60Return codes
61
62    200  Success
63    400  Invalid certificate and private key file.
64    405  Method not supported.
65    500  Internal server error
66
67```
68
69## CSR
70
71### User flow for generating and installing Certificates(CSR Based)
72
73[Certificate Signing Request][csr](CSR) is a message sent from an applicant to a
74certitificate authority in order to apply for a digital identity certificate.
75This section provides the details of the CSR based certificate user flow.
76
77- The user performs the CSR/create interface BMC creates new private key and CSR
78  object which includes CSR information.
79- The user performs the CSR/export interface Allows the user to export the CSR
80  file which is part of newly created CSR object. This can be provided to the CA
81  to create SSL certificate.
82- The user perform the certificate upload on appropriate services. Example: if
83  trying to replace the HTTPS certificate for a Manager, navigate to the
84  Manager’s Certificate object upload interface. The Upload method internally
85  pairs the private key used in the first step with the installed certificate.
86
87[csr]: https://en.wikipedia.org/wiki/Certificate_signing_request
88
89### Assumptions
90
91- BMC updates the private key associated to CSR for any new CSR request.
92- BMC upload process automatically appends certificate file with system CSR
93  private key, for the service which requires certificate and key.
94- CSR based Certificate validation is alway's based on private key in the
95  system.
96
97### CSR Request
98
99- CSR requests initiated through D-Bus are time-consuming and might result D-Bus
100  time-out error.
101- To overcome the time-out error, parent process is forked and CSR operation is
102  performed in the child process so that parent process can return the calling
103  thread immediately.
104- OpenSSL library is used in generating CSR based on the algorithm type.
105- At present supporting generating CSR for only "RSA" algorithm type.
106- Parent process registers child process PID and a callback method in the
107  sd_event_lopp so that callback method is invoked upon completion the CSR
108  request in the child process.
109- Callback method invoked creates a CSR object with the status of the CSR
110  operation returned from the child process.
111- CSR read operation will return the CSR string if status is SUCCESS else throws
112  InternalFailure exception to the caller.
113- Certificate Manager implements "/xyz/openbmc_project/Certs/CSR/Create"
114  interface.
115- CSR object created implements "/xyz/openbmc_project/Certs/CSR" interface.
116- Caller needs to validate the CSR request parameters.
117- Caller need to wait on "InterfacesAdded" signal generated upon creation of the
118  CSR object to start reading CSR string.
119
120### Example usage for the GenerateCSR POST request
121
122```yaml
123url: /redfish/v1/CertificateService
124Action: #CertificateService.GenerateCSR {
125    "City": "HYB",
126    "CertificateCollection":
127        "/redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/",
128    "CommonName": "www.company.com",
129    "ContactPerson":"myname",
130    "AlternativeNames":["mycompany.com","mycompany2.com"],
131    "ChallengePassword":"abc123",
132    "Email":"xxx@xx.com",
133    "GivenName":"localhost",
134    "Initials":"G",
135    "Country": "IN",
136    "KeyCurveId":"0",
137    "KeyUsage":["ServerAuthentication","ServerAuthentication"],
138    "KeyBitLength": 2048,
139    "KeyPairAlgorithm": "RSA",
140    "Organization": "ABCD",
141    "OrganizationUnit": "XY",
142    "State": "TX",
143    "SurName": "XX",
144    "UnstructuredName": "xxx"
145}
146Description: This is used to perform a certificate signing request.
147Method: POST
148
149```
150
151### Additional interfaces
152
153- CertificateService.ReplaceCertificate Allows the user to replace an existing
154  certificate.
155
156### d-bus interfaces
157
158#### d-bus interface to install certificate and private Key
159
160- Certs application must:
161  - validate the certificate and Private key file by checking, if the Private
162    key matches the public key in the certificate file.
163  - copy the certificate and Public Key file to the service specific path based
164    on a configuration file.
165  - Reload the listed service(s) for which the certificate is updated.
166
167#### d-bus interface to Delete certificate and Private Key
168
169- certificate manager should provide interface to delete the existing
170  certificate.
171- In case of server type certificate deleting a signed certificate will create a
172  new self signed certificate and will install the same.
173
174### Boot process
175
176- certificate management instances should be created based on the system
177  configuration.
178
179- In case of no Https certificate or invalid Https certificate, certificate
180  manager should update the https certificate with self signed certificate.
181
182### Repository
183
184phosphor-certificate-manager
185
186### Redfish Certificate Support
187
188#### Certificate Upload
189
190- Certificate Manager implements "xyz.openbmc_project.Certs.Install" interface
191  for installing certificates in the system.
192- Redfish initiates certificate upload by issuing a POST request on the Redfish
193  CertificateCollection with the certificate file. Acceptable body formats are:
194  raw pem text or json that is acceptable by action
195  [CertificateService.ReplaceCertificate](https://www.dmtf.org/sites/default/files/standards/documents/DSP2046_2019.1.pdf)
196
197  For example the HTTPS certificate upload POST request is issued on URI
198  "/redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates"
199
200- Bmcweb receives the POST request and it maps the Redfish URI to the
201  corresponding Certificate Manager D-Bus URI. e.g: HTTPS certificate collection
202  URI /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates mapped to
203  /xyz/openbmc_project/certs/server/https.
204- Bmcweb initiates an asynchronous call which invokes the "Install" method of
205  the Certificate Manager.
206- Certificate Manager "Install" method validates, installs the certificate file
207  and creates a Certificate object.
208- Certificate Manager initiates Reload of the Bmcweb service to trigger
209  configuration reload.
210- BMCweb service raises SIGHUP signal as part of Reload.
211- Bmcweb application handles the SIGHUP signal and reloads the SSL context with
212  the installed certificate.
213- Bmcweb invokes the Callback method with the status of the "Install" method
214  received from the Certificate Manager.
215- Callback method set the response message with error details for failure, sets
216  the response message with newly created certificate details for success.
217- Certificate object D-Bus path mapped to corresponding Redfish certificate URI.
218  e.g: /xyz/openbmc_project/certs/server/https/1 is mapped to
219  /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/1 ID of the
220  certificate is appended to the collection URI.
221
222#### Certificate Replace
223
224- Certificate Object implements "xyz.openbmc_project.Certs.Replace" interface to
225  for replacing existing certificate.
226- Redfish issues Replace certificate request by invoking the ReplaceCertificate
227  action of the CertificateService.
228- Redfish Certificate Collection URI is mapped to corresponding Certificate
229  D-Bus object URI e.g: HTTPS certificate object 1 URI
230  /redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/1 is mapped to
231  /xyz/openbmc_project/certs/server/https/1.
232- Bmcweb receives POST request for Replace Certificate, invokes the Replace
233  D-Bus method of the Certificate object asynchronously.
234- Callback method will be passed to the bmcweb asynchronous method which will
235  called after completion of the D-Bus Replace method.
236- Callback method checks the response received, if failure response message is
237  set with error details, if success response message is set with the replaced
238  certificate details.
239
240#### Boot up
241
242- During boot up certificate objects created for the existing certificates.
243
244### Errors thrown by Certificate Manager
245
246- NotAllowed exception thrown if Install method invoked with a certificate
247  already existing. At present only one certificate per server and client
248  certificate type is allowed.
249- InvalidCertificate exception thrown for validation errors.
250
251#### Certificate Deletion
252
253- For server and client certificate type the certificate deletion is not
254  allowed. In case of authority certificate type the delete option is acceptable
255  and can be done on individual certificates, for example:
256
257```plain
258url: redfish/v1/Managers/bmc/Truststore/Certificates/1
259Method: DELETE
260
261Returns: code 204 with empty body content.
262```
263