282 lines
14 KiB
Markdown
282 lines
14 KiB
Markdown
|
# Redfish TLS User Authentication
|
||
|
|
|
||
|
|
Author: Kamil Kowalski <kamil.kowalski@intel.com>
|
||
|
|
|
||
|
|
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.
|