Add design for authorities list management
To support authorities list, we propose to add two interfaces to the
Authority Manager (the authority type of certificate manager):
1. InstallAll
2. ReplaceAll
Signed-off-by: Nan Zhou <nanzhoumails@gmail.com>
Change-Id: I9a26765c4162d515c8bc6ae1e8544e36cbbf0f14
diff --git a/designs/management-console/Authorities_List_Management.md b/designs/management-console/Authorities_List_Management.md
new file mode 100644
index 0000000..448eded
--- /dev/null
+++ b/designs/management-console/Authorities_List_Management.md
@@ -0,0 +1,104 @@
+# Authorities List Management
+
+Author:
+ Nan Zhou (nanzhoumails@gmail.com)
+
+Primary assignee:
+ Nan Zhou
+
+Created:
+ 12/01/2021
+
+## Problem Description
+
+There are use cases where a system has multiple root certificates installed
+to verify different clients. For example, In Google, a trust bundle file (
+which is a list of authorities) is installed on BMC for mTLS authentication.
+
+The current phosphor-certificate-manager doesn't have good support to manage
+multiple root certificates:
+
+1. It only allows replacing a single Authority object in dbus; however,
+Google's use case requires bulk replacement (see the ReplaceAll interface
+below)
+
+2. It only extracts the first certificate given a PEM encoded file
+with multiple certs; however, Google's trust bundle file contains multiple
+PEM encoded certificates
+
+## Requirements
+
+
+
+Phosphor-certificate-manager (only the Authority Manager) and BMCWeb will
+support authorities list:
+
+1. Bulk Installation: given a PEM file with multiple root certificates, it
+validates & installs all of them and returns a list of created objects
+
+2. Bulk Replacement: given a PEM file with multiple root certificates, it will
+firstly delete all current root certificates and redo the installation
+
+3. Redfish: BMCWeb will export all authorities as Redfish Certificate
+
+4. Recovery at boot up: when the phosphor-certificate-manager gets
+instantiated, if it finds a authorities list in the installation path, it
+will recover from the list via a bulk installation
+
+5. Atomic: Bulk Installation and Bulk Replacement are atomic; that is, if
+there is an invalid certificate in the list, the service won't install any of
+the certificates in the list
+
+## Proposed Design
+
+We propose two new interfaces:
+1. InstallAll
+2. ReplaceAll
+
+### xyz.openbmc_project.Certs.InstallAll
+
+When certificate type is Authority, rather than just extract the first
+certificate, we will iterate through each certificate, validate it, create
+corresponding object in DBus, dump individual certificates into PEM files in
+the installation path, creates alias according to subject hash
+(requirements from boost's `ssl_context`) for each certificate, and finally
+copy the PEM file to the installation path(the PEM file will have a fixed
+name)
+
+We return all created object paths as a vector of strings.
+
+For other types of certificates (server & client), the service throws a NOT
+ALLOWED error.
+
+### xyz.openbmc_project.Certs.ReplaceAll
+
+The new interface contains a ReplaceAll method which takes a path to the input
+PEM file.
+
+The certificate manager will implement the new ReplaceAll interface. Upon
+invocation, it deletes all current authority objects, takes the input PEM,
+and redo the installation.
+
+For other types of certificate manager (server & client), the service throws a
+NOT ALLOWED error.
+
+### xyz.openbmc_project.Certs.Replace
+
+No changes. Individual authority certificate can still be replaced
+respectively. It only extracts the first certificate even if the PEM contains
+multiple root certificates.
+
+## Impacts
+
+None besides new APIs are added
+
+## Alternatives Considered
+
+We can also create a trust bundle interface (instead of using multiple
+Certificates) and implement its standalone manager daemon. It has less impact
+in existing codes. However, trust bundle isn't in BMCWeb, neither in Redfish
+schema.
+
+## Testing
+Enhance existing unit tests in phosphor-certificates-manager to test bulk
+installation and replacements.