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