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