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