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