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