Redfish TLS User Authentication design proposal
This document is a draft design for extending BMCWeb's
authentication flow with TLS User Authentication through
usage of user certificates.
Signed-off-by: Kamil Kowalski <kamil.kowalski@intel.com>
Change-Id: I1a0056cf661b7fae64f9de580d9b7dbedb32a86d
Signed-off-by: Kamil Kowalski <kamil.kowalski@intel.com>
diff --git a/designs/redfish-tls-user-authentication.md b/designs/redfish-tls-user-authentication.md
new file mode 100644
index 0000000..6bd3bc0
--- /dev/null
+++ b/designs/redfish-tls-user-authentication.md
@@ -0,0 +1,284 @@
+# Redfish TLS User Authentication
+
+Author:
+ Kamil Kowalski <kamil.kowalski@intel.com>
+
+Primary assignee:
+ Kamil Kowalski
+
+Other contributors:
+ None
+
+Created:
+ June 7, 2019
+
+## Problem Description
+
+Redfish API presented by [BMCWeb](https://github.com/openbmc/bmcweb) allows user
+to authenticate using quite a few methods, eg. BasicAuth, Sessions, etc. In
+addition to those user can gain access to nodes by providing certificate upon
+negotiating HTTPS connection for identifications. The design and principles
+behind this solution are described below.
+
+## Background and References
+
+Redfish currently lacks support for modern authentication methods. Certificate
+based auth would allow for more secure and controllable access control. Using
+SSL certificates provides validity periods, ability to revoke access from CA
+level, and many other security features.
+
+Reference documents:
+- [Certificate Schema Definition](https://redfish.dmtf.org/schemas/v1/Certificate_v1.xml)
+- [CertificateLocations Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateLocations_v1.xml)
+- [CertificateService Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateService_v1.xml)
+- [DSP-IS0008 DMTF's Redfish Certificate Management Document](https://www.dmtf.org/dsp/DSP-IS0008)
+- [RFC 5246 - TLS 1.2 Specification](https://tools.ietf.org/html/rfc5246)
+- [RFC 8446 - TLS 1.3 Specification](https://tools.ietf.org/html/rfc8446)
+
+### Dictionary
+**Redfish API** - Redfish API as defined by DMTF
+**Redfish** - Redfish API implementation in BMCWeb
+
+## Requirements
+
+Adding this would benefit WebUI's and Redfish API's security greatly, and would
+push it towards modern security standards compliance.
+
+## Proposed Design
+
+### Process overview
+
+Whenever ``CA``'s certificate changes ``User`` shall provide ``Redfish`` with
+it. After that is completed, user should request a **CSR** (**C**ertificate
+**S**igning **R**equest) from ``Redfish`` to get a request allowing to generate
+proper ``user``'s certificate from ``CA``. After this
+certificate is acquired, ``User`` can use this certificate when initializing
+HTTPS sessions.
+
+```
+┌──┐ ┌────┐ ┌───────┐
+│CA│ │User│ │Redfish│
+└┬─┘ └─┬──┘ └───┬───┘
+ │ Request CA's certificate │ │
+ │ <────────────────────────────── │
+ │ │ │
+ │ Return CA's certificate │ │
+ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │
+ │ │ │
+ │ │ Upload CA Certificate │
+ │ │ ───────────────────────────────────────>
+ │ │ │
+ │ ──────────┐ │
+ │ │ Generate CSR │
+ │ <─────────┘ │
+ │ │ │
+ │ Request certificate using CSR │ │
+ │ <────────────────────────────── │
+ │ │ │
+ │ Return User's certificate │ │
+ │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │
+ │ │ │
+ │ │ │
+ │ ╔═══════╤═══╪════════════════════════════════════════╪════╗
+ │ ║ LOOP │ Typical runtime │ ║
+ │ ╟───────┘ │ │ ║
+ │ ║ │ Initiate HTTPS Session │ ║
+ │ ║ │ ───────────────────────────────────────> ║
+ │ ║ │ │ ║
+ │ ║ │ Request TLS client authentication │ ║
+ │ ║ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║
+ │ ║ │ │ ║
+ │ ║ │ Provide certificate │ ║
+ │ ║ │ ───────────────────────────────────────> ║
+ │ ║ │ │ ║
+ │ ║ │ Return requested data │ ║
+ │ ║ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║
+ │ ╚═══════════╪════════════════════════════════════════╪════╝
+┌┴─┐ ┌─┴──┐ ┌───┴───┐
+│CA│ │User│ │Redfish│
+└──┘ └────┘ └───────┘
+```
+
+### BMCWeb / Redfish API
+
+#### Uploading CA Certificate
+
+CA's certificates for user authentication are kept at
+``/redfish/v1/AccountService/TLSAuth/Certificates``. There can be
+more than one, so user must use certificate that is signed by **any CA** that
+have their valid certificate stored there. New certificates can be uploaded
+by *POST*ing new certificate object on CertificateCollection.
+
+Example POST payload:
+```json
+{
+ "CertificateString": "... <Certificate String> ...",
+ "CertificateType": "PEM"
+}
+```
+
+Should CA certificate get invalid (compromised, out-of-date, etc.) it is
+recommended to use ``#CertificateService.ReplaceCertificate`` action at
+``/redfish/v1/CertificateService``, to avoid wasting space and performance
+unnecessarily for processing invalid certificates.
+
+Example ``#CertificateService.ReplaceCertificate`` action payload executed on
+``/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate``:
+
+```json
+{
+ "CertificateUri": "/redfish/v1/AccountService/TLSAuth/Certificates/1",
+ "CertificateString": "... <Certificate String> ...",
+ "CertificateType": "PEM"
+}
+```
+
+#### Generating CSR
+
+User can generate CSR in any way that is convenient to him.
+
+#### Authentication Process
+
+```
+ +-+
+ +++
+ |
+ V
+ +------------+------------+
+ Yes | |
+ +---------+ Is certificate valid |
+ | | and signed by known CA? |
+ | | |
+ | +------------+------------+
+ | |
+ | | No
+ | V
+ | +-----------+-----------+
+ | Yes | |
+ +----------+ Is URI whitelisted? |
+ | | |
+ | +-----------+-----------+
+ | |
+ | | No
+ | V
+ | +-----------+-----------+
+ | Yes | |
+ +----------+ Is X-Token provided? |
+ | | |
+ | +-----------+-----------+
+ | |
+ | | No
+ | V
+ | +-----------+-----------+
+ | Yes | |
+ +----------+ Is cookie provided? |
+ | | |
+ | +-----------+-----------+
+ | |
+ | | No
+ | V
+ | +-----------+-----------+
+ | Yes | |
+ +----------+ Is Token provided? |
+ | | |
+ | +-----------+-----------+
+ | |
+ | | No
+ | V
+ | +---------------+--------------+
+ | Yes | | No
+ +------+ Is Basic auth data provided? +------+
+ | | | |
+ | +------------------------------+ |
+ V V
++-------------+--------------+ +-------------+--------------+
+| | | |
+| Create session | | Return authorization error |
+| | | |
++-------------+--------------+ +-------------+--------------+
+ | |
+ | +-+ |
+ +--------------------->*<--------------------+
+ +-+
+```
+
+Certificate based authentication has the highest priority, because of the design
+of *Boost.Beast/Boost.ASIO/OpenSSL* as the certificate verification is being
+done at the very beginning of HTTPS request processing. *OpenSSL* library is
+responsible for determining whether certificate is valid or not. For certificate
+to be marked as valid, it (and every certificate in chain) has to meet these
+conditions:
+- does KeyUsage contain required data ("digitalSignature" and "keyAgreement")
+- does ExtendedKeyUsage contain required data (contains "clientAuth")
+- public key meets minimal bit length requirement
+- certificate has to be in it's validity period
+- notBefore and notAfter fields have to contain valid time
+- has to be properly signed by certificate authority
+- certificate cannot be revoked
+- certificate is well-formed according to X.509
+- certificate cannot be self-signed
+- issuer name has to match CA's subject name
+
+After these checks a callback is invoked providing result of user<->CA matching
+status. There, in case of success Redfish extracts username from ``CommonName``
+and verifies if user does exist in the system.
+
+As can be seen on the flow diagram, Redfish will use **the first valid**
+credentials according to processing sequence. It is recommended for user to use
+only one set of credentials/authentication data in a single request to be sure
+what will be used, otherwise there is no certainty which credential are used
+during operation.
+
+User can configure which methods are available in ``/redfish/v1/AccountService``
+OEM schema. The sequence of credential verification stays the same regardless
+of configuration. Whitelist verification is always-on, because of Redfish
+specification and other accessibility requirements.
+
+User certificate does not have to be signed by the exact CAs whose certificates
+are stored, but instead it can be done in a chain (Redfish guarantees support
+for chain depth up to 5, but greater ones may work as well). It is recommended
+to use at least 2048bit RSA or 256/384bit elliptic curve keys. Certificate has
+to be in its validity period in the moment of session initialization.
+
+#### Authorization
+
+User identified by any of methods described above, goes through process of
+examining whether user actually exists, and what privileges, groups, etc. should
+be provided. Current base is BasicAuth as it should be used for creating
+sessions which can be used in following connections, and it is executed by
+BMCWeb through PAM library usage. Other auth methods have access only to user's
+login credentials without password, so verification of user existence cannot be
+directly done through classic PAM flow, and should be done in other way. This
+also applies for certificate based auth, so all non BasicAuth methods should
+verify whether user exists and is not locked out of the system on any login
+attempt.
+
+## Alternatives Considered
+
+None.
+
+## Impacts
+
+Current auth methods will not be impacted. This proposition is based on locally
+stored CA certificates, so it does not guarantee automated measures against
+situations where certificates have been revoked, and user/admin has not yet
+updated certificates on BMC.
+
+## Testing
+
+Testing should be conducted on currently supported auth methods beside TLS, to
+confirm that their behavior did not change, and did not suffer any regression.
+
+As for TLS auth itself:
+1. Flow described in [Process overview](###process-overview)
+should be tested, to confirm that after going through it, everything works as
+expected.
+2. Validity period tests - to confirm that certificates that are not-yet-valid
+and expired ones are not accepted, by both - changing validity periods in
+certificates themselves, as well as modifying time on BMC itself
+3. Removing CA certificate and confirming that user will not be granted access
+after that when using certificate that worked before removal.
+4. Chain certificates verification - checking that chained certificates are
+accepted as required.
+5. Negative tests for breaking user's certificate - invalid username, invalid
+validity period, invalid CA, binary broken certificate, etc.