1# Redfish TLS User Authentication
2
3Author:
4  Kamil Kowalski <kamil.kowalski@intel.com>
5
6Other contributors:
7  None
8
9Created:
10  June 7, 2019
11
12## Problem Description
13
14Redfish API presented by [BMCWeb](https://github.com/openbmc/bmcweb) allows user
15to authenticate using quite a few methods, eg. BasicAuth, Sessions, etc. In
16addition to those user can gain access to nodes by providing certificate upon
17negotiating HTTPS connection for identifications. The design and principles
18behind this solution are described below.
19
20## Background and References
21
22Redfish currently lacks support for modern authentication methods. Certificate
23based auth would allow for more secure and controllable access control. Using
24SSL certificates provides validity periods, ability to revoke access from CA
25level, and many other security features.
26
27Reference documents:
28- [Certificate Schema Definition](https://redfish.dmtf.org/schemas/v1/Certificate_v1.xml)
29- [CertificateLocations Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateLocations_v1.xml)
30- [CertificateService Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateService_v1.xml)
31- [DSP-IS0008 DMTF's Redfish Certificate Management Document](https://www.dmtf.org/dsp/DSP-IS0008)
32- [RFC 5246 - TLS 1.2 Specification](https://tools.ietf.org/html/rfc5246)
33- [RFC 8446 - TLS 1.3 Specification](https://tools.ietf.org/html/rfc8446)
34
35### Dictionary
36**Redfish API** - Redfish API as defined by DMTF
37**Redfish** - Redfish API implementation in BMCWeb
38
39## Requirements
40
41Adding this would benefit WebUI's and Redfish API's security greatly, and would
42push it towards modern security standards compliance.
43
44## Proposed Design
45
46### Process overview
47
48Whenever ``CA``'s certificate changes ``User`` shall provide ``Redfish`` with
49it. After that is completed, user should request a **CSR** (**C**ertificate
50**S**igning **R**equest) from ``Redfish`` to get a request allowing to generate
51proper ``user``'s certificate from ``CA``. After this
52certificate is acquired, ``User`` can use this certificate when initializing
53HTTPS sessions.
54
55```
56┌──┐                           ┌────┐                                 ┌───────┐
57│CA│                           │User│                                 │Redfish│
58└┬─┘                           └─┬──┘                                 └───┬───┘
59 │    Request CA's certificate   │                                        │
60 │ <──────────────────────────────                                        │
61 │                               │                                        │
62 │    Return CA's certificate    │                                        │
63 │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─>                                        │
64 │                               │                                        │
65 │                               │          Upload CA Certificate         │
66 │                               │ ───────────────────────────────────────>
67 │                               │                                        │
68 │                               ──────────┐                              │
69 │                                         │ Generate CSR                 │
70 │                               <─────────┘                              │
71 │                               │                                        │
72 │ Request certificate using CSR │                                        │
73 │ <──────────────────────────────                                        │
74 │                               │                                        │
75 │   Return User's certificate   │                                        │
76 │  ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─>                                        │
77 │                               │                                        │
78 │                               │                                        │
79 │                   ╔═══════╤═══╪════════════════════════════════════════╪════╗
80 │                   ║ LOOP  │  Typical runtime                           │    ║
81 │                   ╟───────┘   │                                        │    ║
82 │                   ║           │         Initiate HTTPS Session         │    ║
83 │                   ║           │ ───────────────────────────────────────>    ║
84 │                   ║           │                                        │    ║
85 │                   ║           │   Request TLS client authentication    │    ║
86 │                   ║           │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─    ║
87 │                   ║           │                                        │    ║
88 │                   ║           │          Provide certificate           │    ║
89 │                   ║           │ ───────────────────────────────────────>    ║
90 │                   ║           │                                        │    ║
91 │                   ║           │          Return requested data         │    ║
92 │                   ║           │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─    ║
93 │                   ╚═══════════╪════════════════════════════════════════╪════╝
94┌┴─┐                           ┌─┴──┐                                 ┌───┴───┐
95│CA│                           │User│                                 │Redfish│
96└──┘                           └────┘                                 └───────┘
97```
98
99### BMCWeb / Redfish API
100
101#### Uploading CA Certificate
102
103CA's certificates for user authentication are kept at
104``/redfish/v1/AccountService/TLSAuth/Certificates``. There can be
105more than one, so user must use certificate that is signed by **any CA** that
106have their valid certificate stored there. New certificates can be uploaded
107by *POST*ing new certificate object on CertificateCollection.
108
109Example POST payload:
110```json
111{
112    "CertificateString": "... <Certificate String> ...",
113    "CertificateType": "PEM"
114}
115```
116
117Should CA certificate get invalid (compromised, out-of-date, etc.) it is
118recommended to use ``#CertificateService.ReplaceCertificate`` action at
119``/redfish/v1/CertificateService``, to avoid wasting space and performance
120unnecessarily for processing invalid certificates.
121
122Example ``#CertificateService.ReplaceCertificate`` action payload executed on
123``/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate``:
124
125```json
126{
127    "CertificateUri": "/redfish/v1/AccountService/TLSAuth/Certificates/1",
128    "CertificateString": "... <Certificate String> ...",
129    "CertificateType": "PEM"
130}
131```
132
133#### Generating CSR
134
135User can generate CSR in any way that is convenient to him.
136
137#### Authentication Process
138
139```
140                                    +-+
141                                    +++
142                                     |
143                                     V
144                        +------------+------------+
145                  Yes   |                         |
146              +---------+  Is certificate valid   |
147              |         | and signed by known CA? |
148              |         |                         |
149              |         +------------+------------+
150              |                      |
151              |                      | No
152              |                      V
153              |          +-----------+-----------+
154              |    Yes   |                       |
155              +----------+  Is URI whitelisted?  |
156              |          |                       |
157              |          +-----------+-----------+
158              |                      |
159              |                      | No
160              |                      V
161              |          +-----------+-----------+
162              |    Yes   |                       |
163              +----------+ Is X-Token provided?  |
164              |          |                       |
165              |          +-----------+-----------+
166              |                      |
167              |                      | No
168              |                      V
169              |          +-----------+-----------+
170              |    Yes   |                       |
171              +----------+  Is cookie provided?  |
172              |          |                       |
173              |          +-----------+-----------+
174              |                      |
175              |                      | No
176              |                      V
177              |          +-----------+-----------+
178              |    Yes   |                       |
179              +----------+   Is Token provided?  |
180              |          |                       |
181              |          +-----------+-----------+
182              |                      |
183              |                      | No
184              |                      V
185              |      +---------------+--------------+
186              | Yes  |                              |  No
187              +------+ Is Basic auth data provided? +------+
188              |      |                              |      |
189              |      +------------------------------+      |
190              V                                            V
191+-------------+--------------+               +-------------+--------------+
192|                            |               |                            |
193|       Create session       |               | Return authorization error |
194|                            |               |                            |
195+-------------+--------------+               +-------------+--------------+
196              |                                            |
197              |                     +-+                    |
198              +--------------------->*<--------------------+
199                                    +-+
200```
201
202Certificate based authentication has the highest priority, because of the design
203of *Boost.Beast/Boost.ASIO/OpenSSL* as the certificate verification is being
204done at the very beginning of HTTPS request processing. *OpenSSL* library is
205responsible for determining whether certificate is valid or not. For certificate
206to be marked as valid, it (and every certificate in chain) has to meet these
207conditions:
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
231of configuration. 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:
2701. Flow described in [Process overview](###process-overview)
271should be tested, to confirm that after going through it, everything works as
272expected.
2732. Validity period tests - to confirm that certificates that are not-yet-valid
274and expired ones are not accepted, by both - changing validity periods in
275certificates themselves, as well as modifying time on BMC itself
2763. Removing CA certificate and confirming that user will not be granted access
277after that when using certificate that worked before removal.
2784. Chain certificates verification - checking that chained certificates are
279accepted as required.
2805. Negative tests for breaking user's certificate - invalid username, invalid
281validity period, invalid CA, binary broken certificate, etc.
282