openbmc_project/Certs/README.md

1 # BMC Certificate management
5 Certificate management allows to replace the existing certificate and private
6 key file with another (possibly certification Authority (CA) signed) certificate
7 and private key file. Certificate management allows the user to install both the
9 certificate, using an unencrypted certificate and private key file in .pem
10 format, which includes both private key and signed certificate.
12 ### Signed Certificate upload Design flow(Pre-generated)
14 - The REST Server copies the certificate and private key file to a temporary
17   The recommendation for the D-Bus application implementing certificate D-Bus
20     certificate application handling Https server certificate.
22     certificate application handling LDAP client certificate.
24     the certificate application handling Certificate Authority certificates.
25 - REST server should call the install method of the certificate application
27 - Certificate manager application also implements d-bus object
30   provide option to view the certificate on PEM format and delete the same.
33   new certificate is uploaded or change in the existing certificates.
34 - Certificate manager scope is limited to manage the certificate and impacted
36 - In case of delete action, certificate manager creates a new self signed
37   certificate after successful delete (regards only server type certificates)
45 Description: Update https server signed certificate and the private key.
49 Description: Delete https server signed certificate and the private key.
53 Description: Update ldap client certificate and the private key.
57 Description: Delete ldap client certificate and the private key.
63     400  Invalid certificate and private key file.
73 [Certificate Signing Request][csr](CSR) is a message sent from an applicant to a
74 certitificate authority in order to apply for a digital identity certificate.
75 This section provides the details of the CSR based certificate user flow.
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.
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
113 - Certificate Manager implements "/xyz/openbmc_project/Certs/CSR/Create"
146 Description: This is used to perform a certificate signing request.
154   certificate.
158 #### d-bus interface to install certificate and private Key
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
165   - Reload the listed service(s) for which the certificate is updated.
167 #### d-bus interface to Delete certificate and Private Key
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.
176 - certificate management instances should be created based on the system
179 - In case of no Https certificate or invalid Https certificate, certificate
180   manager should update the https certificate with self signed certificate.
184 phosphor-certificate-manager
186 ### Redfish Certificate Support
188 #### Certificate Upload
190 - Certificate Manager implements "xyz.openbmc_project.Certs.Install" interface
192 - Redfish initiates certificate upload by issuing a POST request on the Redfish
193   CertificateCollection with the certificate file. Acceptable body formats are:
197   For example the HTTPS certificate upload POST request is issued on URI
201   corresponding Certificate Manager D-Bus URI. e.g: HTTPS certificate collection
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
212   the installed certificate.
214   received from the Certificate Manager.
216   the response message with newly created certificate details for success.
217 - Certificate object D-Bus path mapped to corresponding Redfish certificate URI.
220   certificate is appended to the collection URI.
222 #### Certificate Replace
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
228 - Redfish Certificate Collection URI is mapped to corresponding Certificate
229   D-Bus object URI e.g: HTTPS certificate object 1 URI
232 - Bmcweb receives POST request for Replace Certificate, invokes the Replace
233   D-Bus method of the Certificate object asynchronously.
238   certificate details.
242 - During boot up certificate objects created for the existing certificates.
244 ### Errors thrown by Certificate Manager
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.
251 #### Certificate Deletion
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