1# Authorities List Management
2
3Author: Nan Zhou (nanzhoumails@gmail.com)
4
5Created: 12/01/2021
6
7## Problem Description
8
9There are use cases where a system has multiple root certificates installed to
10verify different clients. For example, In Google, a trust bundle file ( which is
11a list of authorities) is installed on BMC for mTLS authentication.
12
13The current phosphor-certificate-manager doesn't have good support to manage
14multiple root certificates:
15
161. It only allows replacing a single Authority object in dbus; however, Google's
17   use case requires bulk replacement (see the ReplaceAll interface below)
18
192. It only extracts the first certificate given a PEM encoded file with multiple
20   certs; however, Google's trust bundle file contains multiple PEM encoded
21   certificates
22
23## Requirements
24
25Phosphor-certificate-manager (only the Authority Manager) and BMCWeb will
26support authorities list:
27
281. Bulk Installation: given a PEM file with multiple root certificates, it
29   validates & installs all of them and returns a list of created objects
30
312. Bulk Replacement: given a PEM file with multiple root certificates, it will
32   firstly delete all current root certificates and redo the installation
33
343. Redfish: BMCWeb will export all authorities as Redfish Certificate
35
364. Recovery at boot up: when the phosphor-certificate-manager gets instantiated,
37   if it finds a authorities list in the installation path, it will recover from
38   the list via a bulk installation
39
405. Atomic: Bulk Installation and Bulk Replacement are atomic; that is, if there
41   is an invalid certificate in the list, the service won't install any of the
42   certificates in the list
43
44## Proposed Design
45
46We propose two new interfaces:
47
481. InstallAll
492. ReplaceAll
50
51### xyz.openbmc_project.Certs.InstallAll
52
53When certificate type is Authority, rather than just extract the first
54certificate, we will iterate through each certificate, validate it, create
55corresponding object in DBus, dump individual certificates into PEM files in the
56installation path, creates alias according to subject hash (requirements from
57boost's `ssl_context`) for each certificate, and finally copy the PEM file to
58the installation path(the PEM file will have a fixed name)
59
60We return all created object paths as a vector of strings.
61
62For other types of certificates (server & client), the service throws a NOT
63ALLOWED error.
64
65### xyz.openbmc_project.Certs.ReplaceAll
66
67The new interface contains a ReplaceAll method which takes a path to the input
68PEM file.
69
70The certificate manager will implement the new ReplaceAll interface. Upon
71invocation, it deletes all current authority objects, takes the input PEM, and
72redo the installation.
73
74For other types of certificate manager (server & client), the service throws a
75NOT ALLOWED error.
76
77### xyz.openbmc_project.Certs.Replace
78
79No changes. Individual authority certificate can still be replaced respectively.
80It only extracts the first certificate even if the PEM contains multiple root
81certificates.
82
83## Impacts
84
85None besides new APIs are added
86
87## Alternatives Considered
88
89We can also create a trust bundle interface (instead of using multiple
90Certificates) and implement its standalone manager daemon. It has less impact in
91existing codes. However, trust bundle isn't in BMCWeb, neither in Redfish
92schema.
93
94## Testing
95
96Enhance existing unit tests in phosphor-certificates-manager to test bulk
97installation and replacements.
98