1# Certificate Revocation List on BMC 2 3Author: Nan Zhou (nanzhoumails@gmail.com) 4 5Primary assignee: Nan Zhou 6 7Created: 02/25/2022 8 9## Problem Description 10 11This design is to add management interfaces for certificate revocation list in 12OpenBMC. 13 14## Background and References 15 16A certificate revocation list (CRL) is a list of digital certificates that 17have been revoked by the issuing certificate authority (CA) before their 18actual or assigned expiration date. In Google, there are use cases that BMC 19needs to install CRLs to the Redfish server, so that clients with revoked 20certificates will be rejected in TLS handshake. Supporting CRL is also 21recommended in most applications. 22 23Current OpenBMC certificate management architecture contains two main 24components. 25 261. [phosphor-certificate-manager](https://github.com/openbmc/phosphor-certificate-manager) 27owns certificate objects and implements management interfaces; currently 28there are three types of certificates supported: client, server, and 29authority. 30 312. [BMCWeb](https://github.com/openbmc/bmcweb): the Redfish front-end which 32translates certificate objects into Redfish resources. BMCWeb is also a 33consumer of these certificates; it uses certificates in its TLS handshake. 34 35DMTF doesn't support CRLs yet in the Redfish spec. Adding them is WIP. See 36[this discussion](https://redfishforum.com/thread/618/resource-certificate-revocation-list?page=1&scrollTo=2173). 37Google doesn't plan on using Redfish interfaces to manage certificates and 38CRLs. Instead, Google has a dedicated daemon for credentials installation, 39and this daemon interacts with the OpenBMC certificate management 40architecture via DBus APIs. 41 42## Requirements 43 44OpenBMC supports management interface for CRLs: 45 461. clients shall be able to install/delete/replace CRLs via DBus APIs 472. whenever CRLs change, the certificate management system shall notify 48consumers which use old CRLs to refresh with the newly given CRLs 493. other daemons, e.g., BMCWeb shall consume CRLs the same way as existing 50authority/server/client certificates, that is, via file path or directory 51determined at compile time. 52 53## Proposed Design 54 55### phosphor-dbus-interfaces 56 57We propose to introduce a new interface `CRL` in [Certs](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs). 58 59Because no Redfish spec is available, we propose the only attribute of the 60interface to be `CRLString`, which contains the PEM encoded CRL. We can add 61more attributes as needed in the future. 62 63### phosphor-certificate-manager 64 65We propose to add a new type of certificate-manager (CRL-manager) to the 66existing three types of Manager. 67 68The CRL-manager will implement the following common interfaces: 69 701. [InstallAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Certs/InstallAll.interface.yaml): 71install multiple CRLs and notify consumers. The notification process is 72the existing behaviour which phosphor-certificate-manager uses to tell 73consumers to reload newly installed credentials. 74 752. [ReplaceAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Certs/ReplaceAll.interface.yaml): 76replace all existing CRLs with multiple new CRLs and notify consumers 77 783. [DeleteAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Collection/DeleteAll.interface.yaml): 79delete all existing CRLs and notify consumers 80 81### BMCWeb 82 83We propose to introduce CRLs into BMCWeb's SSL Context. Whenever BMCWeb 84reloads, it not only refreshes authority and server certificates, but also 85CRLs. Example codes can be found in many opensource projects, e.g., this 86[snippet](https://github.com/Icinga/icinga2/blob/master/lib/base/tlsutility.cpp#L338). 87 88## Alternatives Considered 89 90We can model the whole CRLs list as a single object, but that's not aligned 91with the existing authorities list design. 92 93## Impacts 94 951. New DBus interfaces 962. More complete security support 97 98## Testing 99 100Add new unit tests in phosphor-certificate-manager. 101 102Manual integration tests: install CRLs and verify clients' revoked 103certificates are rejected. 104