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