openbmc_project/Certs/README.md

1 # BMC Certificate management
5 Certificate management allows to replace the existing certificate and private
7 and private key file. Certificate management allows the user to install both the
12 ### Signed Certificate upload Design flow(Pre-generated)
14 - The REST Server copies the certificate and private key file to a temporary
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
19   - The URI /xyz/openbmc_project/certs/server/https maps to instance of the
21   - The URI /xyz/openbmc_project/certs/client/ldap maps to instance of the
23   - The URI /xyz/openbmc_project/certs/authority/truststore maps to instance of
25 - REST server should call the install method of the certificate application
27 - Certificate manager application also implements d-bus object
29   "certificates specific d-bus objects" installed in the system. This d-bus
31   Refer [Wikipedia][privacy-enhanced-mail] for details.
32 - Applications should subscribe the xyz.openbmc_project.Certs.Manager to see any
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
39 [privacy-enhanced-mail]: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
71 ### User flow for generating and installing Certificates(CSR Based)
75 This section provides the details of the CSR based certificate user flow.
77 - The user performs the CSR/create interface BMC creates new private key and CSR
79 - The user performs the CSR/export interface Allows the user to export the CSR
82 - The user perform the certificate upload on appropriate services. Example: if
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
94 - CSR based Certificate validation is alway's based on private key in the
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
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
109 - Callback method invoked creates a CSR object with the status of the CSR
111 - CSR read operation will return the CSR string if status is SUCCESS else throws
113 - Certificate Manager implements "/xyz/openbmc_project/Certs/CSR/Create"
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
153 - CertificateService.ReplaceCertificate Allows the user to replace an existing
156 ### d-bus interfaces
158 #### d-bus interface to install certificate and private Key
160 - Certs application must:
161   - validate the certificate and Private key file by checking, if the Private
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
171 - In case of server type certificate deleting a signed certificate will create a
176 - certificate management instances should be created based on the system
179 - In case of no Https certificate or invalid Https certificate, certificate
184 phosphor-certificate-manager
190 - Certificate Manager implements "xyz.openbmc_project.Certs.Install" interface
192 - Redfish initiates certificate upload by issuing a POST request on the Redfish
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
204 - Bmcweb initiates an asynchronous call which invokes the "Install" method of
206 - Certificate Manager "Install" method validates, installs the certificate file
208 - Certificate Manager initiates Reload of the Bmcweb service to trigger
210 - BMCweb service raises SIGHUP signal as part of Reload.
211 - Bmcweb application handles the SIGHUP signal and reloads the SSL context with
213 - Bmcweb invokes the Callback method with the status of the "Install" method
215 - Callback method set the response message with error details for failure, sets
217 - Certificate object D-Bus path mapped to corresponding Redfish certificate URI.
224 - Certificate Object implements "xyz.openbmc_project.Certs.Replace" interface to
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.
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
242 - During boot up certificate objects created for the existing certificates.
246 - NotAllowed exception thrown if Install method invoked with a certificate
249 - InvalidCertificate exception thrown for validation errors.
253 - For server and client certificate type the certificate deletion is not