1# Redfish TLS User Authentication
2
3Author: Kamil Kowalski <kamil.kowalski@intel.com>
4
5Other contributors: None
6
7Created: June 7, 2019
8
9## Problem Description
10
11Redfish API presented by [BMCWeb](https://github.com/openbmc/bmcweb) allows user
12to authenticate using quite a few methods, eg. BasicAuth, Sessions, etc. In
13addition to those user can gain access to nodes by providing certificate upon
14negotiating HTTPS connection for identifications. The design and principles
15behind this solution are described below.
16
17## Background and References
18
19Redfish currently lacks support for modern authentication methods. Certificate
20based auth would allow for more secure and controllable access control. Using
21SSL certificates provides validity periods, ability to revoke access from CA
22level, and many other security features.
23
24Reference documents:
25
26- [Certificate Schema Definition](https://redfish.dmtf.org/schemas/v1/Certificate_v1.xml)
27- [CertificateLocations Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateLocations_v1.xml)
28- [CertificateService Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateService_v1.xml)
29- [DSP-IS0008 DMTF's Redfish Certificate Management Document](https://www.dmtf.org/dsp/DSP-IS0008)
30- [RFC 5246 - TLS 1.2 Specification](https://tools.ietf.org/html/rfc5246)
31- [RFC 8446 - TLS 1.3 Specification](https://tools.ietf.org/html/rfc8446)
32
33### Dictionary
34
35**Redfish API** - Redfish API as defined by DMTF **Redfish** - Redfish API
36implementation in BMCWeb
37
38## Requirements
39
40Adding this would benefit WebUI's and Redfish API's security greatly, and would
41push it towards modern security standards compliance.
42
43## Proposed Design
44
45### Process overview
46
47Whenever `CA`'s certificate changes `User` shall provide `Redfish` with it.
48After that is completed, user should request a **CSR** (**C**ertificate
49**S**igning **R**equest) from `Redfish` to get a request allowing to generate
50proper `user`'s certificate from `CA`. After this certificate is acquired,
51`User` can use this certificate when initializing HTTPS sessions.
52
53```
54┌──┐                           ┌────┐                                 ┌───────┐
55│CA│                           │User│                                 │Redfish│
56└┬─┘                           └─┬──┘                                 └───┬───┘
57 │    Request CA's certificate   │                                        │
58 │ <──────────────────────────────                                        │
59 │                               │                                        │
60 │    Return CA's certificate    │                                        │
61 │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─>                                        │
62 │                               │                                        │
63 │                               │          Upload CA Certificate         │
64 │                               │ ───────────────────────────────────────>
65 │                               │                                        │
66 │                               ──────────┐                              │
67 │                                         │ Generate CSR                 │
68 │                               <─────────┘                              │
69 │                               │                                        │
70 │ Request certificate using CSR │                                        │
71 │ <──────────────────────────────                                        │
72 │                               │                                        │
73 │   Return User's certificate   │                                        │
74 │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─>                                        │
75 │                               │                                        │
76 │                               │                                        │
77 │                   ╔═══════╤═══╪════════════════════════════════════════╪════╗
78 │                   ║ LOOP  │  Typical runtime                           │    ║
79 │                   ╟───────┘   │                                        │    ║
80 │                   ║           │         Initiate HTTPS Session         │    ║
81 │                   ║           │ ───────────────────────────────────────>    ║
82 │                   ║           │                                        │    ║
83 │                   ║           │   Request TLS client authentication    │    ║
84 │                   ║           │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─    ║
85 │                   ║           │                                        │    ║
86 │                   ║           │          Provide certificate           │    ║
87 │                   ║           │ ───────────────────────────────────────>    ║
88 │                   ║           │                                        │    ║
89 │                   ║           │          Return requested data         │    ║
90 │                   ║           │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─    ║
91 │                   ╚═══════════╪════════════════════════════════════════╪════╝
92┌┴─┐                           ┌─┴──┐                                 ┌───┴───┐
93│CA│                           │User│                                 │Redfish│
94└──┘                           └────┘                                 └───────┘
95```
96
97### BMCWeb / Redfish API
98
99#### Uploading CA Certificate
100
101CA's certificates for user authentication are kept at
102`/redfish/v1/AccountService/TLSAuth/Certificates`. There can be more than one,
103so user must use certificate that is signed by **any CA** that have their valid
104certificate stored there. New certificates can be uploaded by *POST*ing new
105certificate object on CertificateCollection.
106
107Example POST payload:
108
109```json
110{
111  "CertificateString": "... <Certificate String> ...",
112  "CertificateType": "PEM"
113}
114```
115
116Should CA certificate get invalid (compromised, out-of-date, etc.) it is
117recommended to use `#CertificateService.ReplaceCertificate` action at
118`/redfish/v1/CertificateService`, to avoid wasting space and performance
119unnecessarily for processing invalid certificates.
120
121Example `#CertificateService.ReplaceCertificate` action payload executed on
122`/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate`:
123
124```json
125{
126  "CertificateUri": "/redfish/v1/AccountService/TLSAuth/Certificates/1",
127  "CertificateString": "... <Certificate String> ...",
128  "CertificateType": "PEM"
129}
130```
131
132#### Generating CSR
133
134User can generate CSR in any way that is convenient to him.
135
136#### Authentication Process
137
138```
139                                    +-+
140                                    +++
141                                     |
142                                     V
143                        +------------+------------+
144                  Yes   |                         |
145              +---------+  Is certificate valid   |
146              |         | and signed by known CA? |
147              |         |                         |
148              |         +------------+------------+
149              |                      |
150              |                      | No
151              |                      V
152              |          +-----------+-----------+
153              |    Yes   |                       |
154              +----------+  Is URI whitelisted?  |
155              |          |                       |
156              |          +-----------+-----------+
157              |                      |
158              |                      | No
159              |                      V
160              |          +-----------+-----------+
161              |    Yes   |                       |
162              +----------+ Is X-Token provided?  |
163              |          |                       |
164              |          +-----------+-----------+
165              |                      |
166              |                      | No
167              |                      V
168              |          +-----------+-----------+
169              |    Yes   |                       |
170              +----------+  Is cookie provided?  |
171              |          |                       |
172              |          +-----------+-----------+
173              |                      |
174              |                      | No
175              |                      V
176              |          +-----------+-----------+
177              |    Yes   |                       |
178              +----------+   Is Token provided?  |
179              |          |                       |
180              |          +-----------+-----------+
181              |                      |
182              |                      | No
183              |                      V
184              |      +---------------+--------------+
185              | Yes  |                              |  No
186              +------+ Is Basic auth data provided? +------+
187              |      |                              |      |
188              |      +------------------------------+      |
189              V                                            V
190+-------------+--------------+               +-------------+--------------+
191|                            |               |                            |
192|       Create session       |               | Return authorization error |
193|                            |               |                            |
194+-------------+--------------+               +-------------+--------------+
195              |                                            |
196              |                     +-+                    |
197              +--------------------->*<--------------------+
198                                    +-+
199```
200
201Certificate based authentication has the highest priority, because of the design
202of _Boost.Beast/Boost.ASIO/OpenSSL_ as the certificate verification is being
203done at the very beginning of HTTPS request processing. _OpenSSL_ library is
204responsible for determining whether certificate is valid or not. For certificate
205to be marked as valid, it (and every certificate in chain) has to meet these
206conditions:
207
208- does KeyUsage contain required data ("digitalSignature" and "keyAgreement")
209- does ExtendedKeyUsage contain required data (contains "clientAuth")
210- public key meets minimal bit length requirement
211- certificate has to be in it's validity period
212- notBefore and notAfter fields have to contain valid time
213- has to be properly signed by certificate authority
214- certificate cannot be revoked
215- certificate is well-formed according to X.509
216- certificate cannot be self-signed
217- issuer name has to match CA's subject name
218
219After these checks a callback is invoked providing result of user<->CA matching
220status. There, in case of success Redfish extracts username from `CommonName`
221and verifies if user does exist in the system.
222
223As can be seen on the flow diagram, Redfish will use **the first valid**
224credentials according to processing sequence. It is recommended for user to use
225only one set of credentials/authentication data in a single request to be sure
226what will be used, otherwise there is no certainty which credential are used
227during operation.
228
229User can configure which methods are available in `/redfish/v1/AccountService`
230OEM schema. The sequence of credential verification stays the same regardless of
231configuration. Whitelist verification is always-on, because of Redfish
232specification and other accessibility requirements.
233
234User certificate does not have to be signed by the exact CAs whose certificates
235are stored, but instead it can be done in a chain (Redfish guarantees support
236for chain depth up to 5, but greater ones may work as well). It is recommended
237to use at least 2048bit RSA or 256/384bit elliptic curve keys. Certificate has
238to be in its validity period in the moment of session initialization.
239
240#### Authorization
241
242User identified by any of methods described above, goes through process of
243examining whether user actually exists, and what privileges, groups, etc. should
244be provided. Current base is BasicAuth as it should be used for creating
245sessions which can be used in following connections, and it is executed by
246BMCWeb through PAM library usage. Other auth methods have access only to user's
247login credentials without password, so verification of user existence cannot be
248directly done through classic PAM flow, and should be done in other way. This
249also applies for certificate based auth, so all non BasicAuth methods should
250verify whether user exists and is not locked out of the system on any login
251attempt.
252
253## Alternatives Considered
254
255None.
256
257## Impacts
258
259Current auth methods will not be impacted. This proposition is based on locally
260stored CA certificates, so it does not guarantee automated measures against
261situations where certificates have been revoked, and user/admin has not yet
262updated certificates on BMC.
263
264## Testing
265
266Testing should be conducted on currently supported auth methods beside TLS, to
267confirm that their behavior did not change, and did not suffer any regression.
268
269As for TLS auth itself:
270
2711. Flow described in [Process overview](###process-overview) should be tested,
272   to confirm that after going through it, everything works as expected.
2732. Validity period tests - to confirm that certificates that are not-yet-valid
274   and expired ones are not accepted, by both - changing validity periods in
275   certificates themselves, as well as modifying time on BMC itself
2763. Removing CA certificate and confirming that user will not be granted access
277   after that when using certificate that worked before removal.
2784. Chain certificates verification - checking that chained certificates are
279   accepted as required.
2805. Negative tests for breaking user's certificate - invalid username, invalid
281   validity period, invalid CA, binary broken certificate, etc.
282