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