138b2c1a2SKamil Kowalski# Redfish TLS User Authentication 238b2c1a2SKamil Kowalski 3*f4febd00SPatrick WilliamsAuthor: Kamil Kowalski <kamil.kowalski@intel.com> 438b2c1a2SKamil Kowalski 5*f4febd00SPatrick WilliamsOther contributors: None 638b2c1a2SKamil Kowalski 7*f4febd00SPatrick WilliamsCreated: June 7, 2019 838b2c1a2SKamil Kowalski 938b2c1a2SKamil Kowalski## Problem Description 1038b2c1a2SKamil Kowalski 1138b2c1a2SKamil KowalskiRedfish API presented by [BMCWeb](https://github.com/openbmc/bmcweb) allows user 1238b2c1a2SKamil Kowalskito authenticate using quite a few methods, eg. BasicAuth, Sessions, etc. In 1338b2c1a2SKamil Kowalskiaddition to those user can gain access to nodes by providing certificate upon 1438b2c1a2SKamil Kowalskinegotiating HTTPS connection for identifications. The design and principles 1538b2c1a2SKamil Kowalskibehind this solution are described below. 1638b2c1a2SKamil Kowalski 1738b2c1a2SKamil Kowalski## Background and References 1838b2c1a2SKamil Kowalski 1938b2c1a2SKamil KowalskiRedfish currently lacks support for modern authentication methods. Certificate 2038b2c1a2SKamil Kowalskibased auth would allow for more secure and controllable access control. Using 2138b2c1a2SKamil KowalskiSSL certificates provides validity periods, ability to revoke access from CA 2238b2c1a2SKamil Kowalskilevel, and many other security features. 2338b2c1a2SKamil Kowalski 2438b2c1a2SKamil KowalskiReference documents: 25*f4febd00SPatrick Williams 2638b2c1a2SKamil Kowalski- [Certificate Schema Definition](https://redfish.dmtf.org/schemas/v1/Certificate_v1.xml) 2738b2c1a2SKamil Kowalski- [CertificateLocations Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateLocations_v1.xml) 2838b2c1a2SKamil Kowalski- [CertificateService Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateService_v1.xml) 2938b2c1a2SKamil Kowalski- [DSP-IS0008 DMTF's Redfish Certificate Management Document](https://www.dmtf.org/dsp/DSP-IS0008) 3038b2c1a2SKamil Kowalski- [RFC 5246 - TLS 1.2 Specification](https://tools.ietf.org/html/rfc5246) 3138b2c1a2SKamil Kowalski- [RFC 8446 - TLS 1.3 Specification](https://tools.ietf.org/html/rfc8446) 3238b2c1a2SKamil Kowalski 3338b2c1a2SKamil Kowalski### Dictionary 34*f4febd00SPatrick Williams 35*f4febd00SPatrick Williams**Redfish API** - Redfish API as defined by DMTF **Redfish** - Redfish API 36*f4febd00SPatrick Williamsimplementation in BMCWeb 3738b2c1a2SKamil Kowalski 3838b2c1a2SKamil Kowalski## Requirements 3938b2c1a2SKamil Kowalski 4038b2c1a2SKamil KowalskiAdding this would benefit WebUI's and Redfish API's security greatly, and would 4138b2c1a2SKamil Kowalskipush it towards modern security standards compliance. 4238b2c1a2SKamil Kowalski 4338b2c1a2SKamil Kowalski## Proposed Design 4438b2c1a2SKamil Kowalski 4538b2c1a2SKamil Kowalski### Process overview 4638b2c1a2SKamil Kowalski 47*f4febd00SPatrick WilliamsWhenever `CA`'s certificate changes `User` shall provide `Redfish` with it. 48*f4febd00SPatrick WilliamsAfter that is completed, user should request a **CSR** (**C**ertificate 49*f4febd00SPatrick Williams**S**igning **R**equest) from `Redfish` to get a request allowing to generate 50*f4febd00SPatrick Williamsproper `user`'s certificate from `CA`. After this certificate is acquired, 51*f4febd00SPatrick Williams`User` can use this certificate when initializing HTTPS sessions. 5238b2c1a2SKamil Kowalski 5338b2c1a2SKamil Kowalski``` 5438b2c1a2SKamil Kowalski┌──┐ ┌────┐ ┌───────┐ 5538b2c1a2SKamil Kowalski│CA│ │User│ │Redfish│ 5638b2c1a2SKamil Kowalski└┬─┘ └─┬──┘ └───┬───┘ 5738b2c1a2SKamil Kowalski │ Request CA's certificate │ │ 5838b2c1a2SKamil Kowalski │ <────────────────────────────── │ 5938b2c1a2SKamil Kowalski │ │ │ 6038b2c1a2SKamil Kowalski │ Return CA's certificate │ │ 6138b2c1a2SKamil Kowalski │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │ 6238b2c1a2SKamil Kowalski │ │ │ 6338b2c1a2SKamil Kowalski │ │ Upload CA Certificate │ 6438b2c1a2SKamil Kowalski │ │ ───────────────────────────────────────> 6538b2c1a2SKamil Kowalski │ │ │ 6638b2c1a2SKamil Kowalski │ ──────────┐ │ 6738b2c1a2SKamil Kowalski │ │ Generate CSR │ 6838b2c1a2SKamil Kowalski │ <─────────┘ │ 6938b2c1a2SKamil Kowalski │ │ │ 7038b2c1a2SKamil Kowalski │ Request certificate using CSR │ │ 7138b2c1a2SKamil Kowalski │ <────────────────────────────── │ 7238b2c1a2SKamil Kowalski │ │ │ 7338b2c1a2SKamil Kowalski │ Return User's certificate │ │ 7438b2c1a2SKamil Kowalski │ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─> │ 7538b2c1a2SKamil Kowalski │ │ │ 7638b2c1a2SKamil Kowalski │ │ │ 7738b2c1a2SKamil Kowalski │ ╔═══════╤═══╪════════════════════════════════════════╪════╗ 7838b2c1a2SKamil Kowalski │ ║ LOOP │ Typical runtime │ ║ 7938b2c1a2SKamil Kowalski │ ╟───────┘ │ │ ║ 8038b2c1a2SKamil Kowalski │ ║ │ Initiate HTTPS Session │ ║ 8138b2c1a2SKamil Kowalski │ ║ │ ───────────────────────────────────────> ║ 8238b2c1a2SKamil Kowalski │ ║ │ │ ║ 8338b2c1a2SKamil Kowalski │ ║ │ Request TLS client authentication │ ║ 8438b2c1a2SKamil Kowalski │ ║ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║ 8538b2c1a2SKamil Kowalski │ ║ │ │ ║ 8638b2c1a2SKamil Kowalski │ ║ │ Provide certificate │ ║ 8738b2c1a2SKamil Kowalski │ ║ │ ───────────────────────────────────────> ║ 8838b2c1a2SKamil Kowalski │ ║ │ │ ║ 8938b2c1a2SKamil Kowalski │ ║ │ Return requested data │ ║ 9038b2c1a2SKamil Kowalski │ ║ │ <─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ║ 9138b2c1a2SKamil Kowalski │ ╚═══════════╪════════════════════════════════════════╪════╝ 9238b2c1a2SKamil Kowalski┌┴─┐ ┌─┴──┐ ┌───┴───┐ 9338b2c1a2SKamil Kowalski│CA│ │User│ │Redfish│ 9438b2c1a2SKamil Kowalski└──┘ └────┘ └───────┘ 9538b2c1a2SKamil Kowalski``` 9638b2c1a2SKamil Kowalski 9738b2c1a2SKamil Kowalski### BMCWeb / Redfish API 9838b2c1a2SKamil Kowalski 9938b2c1a2SKamil Kowalski#### Uploading CA Certificate 10038b2c1a2SKamil Kowalski 10138b2c1a2SKamil KowalskiCA's certificates for user authentication are kept at 102*f4febd00SPatrick Williams`/redfish/v1/AccountService/TLSAuth/Certificates`. There can be more than one, 103*f4febd00SPatrick Williamsso user must use certificate that is signed by **any CA** that have their valid 104*f4febd00SPatrick Williamscertificate stored there. New certificates can be uploaded by *POST*ing new 105*f4febd00SPatrick Williamscertificate object on CertificateCollection. 10638b2c1a2SKamil Kowalski 10738b2c1a2SKamil KowalskiExample POST payload: 108*f4febd00SPatrick Williams 10938b2c1a2SKamil Kowalski```json 11038b2c1a2SKamil Kowalski{ 11138b2c1a2SKamil Kowalski "CertificateString": "... <Certificate String> ...", 11238b2c1a2SKamil Kowalski "CertificateType": "PEM" 11338b2c1a2SKamil Kowalski} 11438b2c1a2SKamil Kowalski``` 11538b2c1a2SKamil Kowalski 11638b2c1a2SKamil KowalskiShould CA certificate get invalid (compromised, out-of-date, etc.) it is 117*f4febd00SPatrick Williamsrecommended to use `#CertificateService.ReplaceCertificate` action at 118*f4febd00SPatrick Williams`/redfish/v1/CertificateService`, to avoid wasting space and performance 11938b2c1a2SKamil Kowalskiunnecessarily for processing invalid certificates. 12038b2c1a2SKamil Kowalski 121*f4febd00SPatrick WilliamsExample `#CertificateService.ReplaceCertificate` action payload executed on 122*f4febd00SPatrick Williams`/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate`: 12338b2c1a2SKamil Kowalski 12438b2c1a2SKamil Kowalski```json 12538b2c1a2SKamil Kowalski{ 12638b2c1a2SKamil Kowalski "CertificateUri": "/redfish/v1/AccountService/TLSAuth/Certificates/1", 12738b2c1a2SKamil Kowalski "CertificateString": "... <Certificate String> ...", 12838b2c1a2SKamil Kowalski "CertificateType": "PEM" 12938b2c1a2SKamil Kowalski} 13038b2c1a2SKamil Kowalski``` 13138b2c1a2SKamil Kowalski 13238b2c1a2SKamil Kowalski#### Generating CSR 13338b2c1a2SKamil Kowalski 13438b2c1a2SKamil KowalskiUser can generate CSR in any way that is convenient to him. 13538b2c1a2SKamil Kowalski 13638b2c1a2SKamil Kowalski#### Authentication Process 13738b2c1a2SKamil Kowalski 13838b2c1a2SKamil Kowalski``` 13938b2c1a2SKamil Kowalski +-+ 14038b2c1a2SKamil Kowalski +++ 14138b2c1a2SKamil Kowalski | 14238b2c1a2SKamil Kowalski V 14338b2c1a2SKamil Kowalski +------------+------------+ 14438b2c1a2SKamil Kowalski Yes | | 14538b2c1a2SKamil Kowalski +---------+ Is certificate valid | 14638b2c1a2SKamil Kowalski | | and signed by known CA? | 14738b2c1a2SKamil Kowalski | | | 14838b2c1a2SKamil Kowalski | +------------+------------+ 14938b2c1a2SKamil Kowalski | | 15038b2c1a2SKamil Kowalski | | No 15138b2c1a2SKamil Kowalski | V 15238b2c1a2SKamil Kowalski | +-----------+-----------+ 15338b2c1a2SKamil Kowalski | Yes | | 15438b2c1a2SKamil Kowalski +----------+ Is URI whitelisted? | 15538b2c1a2SKamil Kowalski | | | 15638b2c1a2SKamil Kowalski | +-----------+-----------+ 15738b2c1a2SKamil Kowalski | | 15838b2c1a2SKamil Kowalski | | No 15938b2c1a2SKamil Kowalski | V 16038b2c1a2SKamil Kowalski | +-----------+-----------+ 16138b2c1a2SKamil Kowalski | Yes | | 16238b2c1a2SKamil Kowalski +----------+ Is X-Token provided? | 16338b2c1a2SKamil Kowalski | | | 16438b2c1a2SKamil Kowalski | +-----------+-----------+ 16538b2c1a2SKamil Kowalski | | 16638b2c1a2SKamil Kowalski | | No 16738b2c1a2SKamil Kowalski | V 16838b2c1a2SKamil Kowalski | +-----------+-----------+ 16938b2c1a2SKamil Kowalski | Yes | | 17038b2c1a2SKamil Kowalski +----------+ Is cookie provided? | 17138b2c1a2SKamil Kowalski | | | 17238b2c1a2SKamil Kowalski | +-----------+-----------+ 17338b2c1a2SKamil Kowalski | | 17438b2c1a2SKamil Kowalski | | No 17538b2c1a2SKamil Kowalski | V 17638b2c1a2SKamil Kowalski | +-----------+-----------+ 17738b2c1a2SKamil Kowalski | Yes | | 17838b2c1a2SKamil Kowalski +----------+ Is Token provided? | 17938b2c1a2SKamil Kowalski | | | 18038b2c1a2SKamil Kowalski | +-----------+-----------+ 18138b2c1a2SKamil Kowalski | | 18238b2c1a2SKamil Kowalski | | No 18338b2c1a2SKamil Kowalski | V 18438b2c1a2SKamil Kowalski | +---------------+--------------+ 18538b2c1a2SKamil Kowalski | Yes | | No 18638b2c1a2SKamil Kowalski +------+ Is Basic auth data provided? +------+ 18738b2c1a2SKamil Kowalski | | | | 18838b2c1a2SKamil Kowalski | +------------------------------+ | 18938b2c1a2SKamil Kowalski V V 19038b2c1a2SKamil Kowalski+-------------+--------------+ +-------------+--------------+ 19138b2c1a2SKamil Kowalski| | | | 19238b2c1a2SKamil Kowalski| Create session | | Return authorization error | 19338b2c1a2SKamil Kowalski| | | | 19438b2c1a2SKamil Kowalski+-------------+--------------+ +-------------+--------------+ 19538b2c1a2SKamil Kowalski | | 19638b2c1a2SKamil Kowalski | +-+ | 19738b2c1a2SKamil Kowalski +--------------------->*<--------------------+ 19838b2c1a2SKamil Kowalski +-+ 19938b2c1a2SKamil Kowalski``` 20038b2c1a2SKamil Kowalski 20138b2c1a2SKamil KowalskiCertificate based authentication has the highest priority, because of the design 202*f4febd00SPatrick Williamsof _Boost.Beast/Boost.ASIO/OpenSSL_ as the certificate verification is being 203*f4febd00SPatrick Williamsdone at the very beginning of HTTPS request processing. _OpenSSL_ library is 20438b2c1a2SKamil Kowalskiresponsible for determining whether certificate is valid or not. For certificate 20538b2c1a2SKamil Kowalskito be marked as valid, it (and every certificate in chain) has to meet these 20638b2c1a2SKamil Kowalskiconditions: 207*f4febd00SPatrick Williams 20838b2c1a2SKamil Kowalski- does KeyUsage contain required data ("digitalSignature" and "keyAgreement") 20938b2c1a2SKamil Kowalski- does ExtendedKeyUsage contain required data (contains "clientAuth") 21038b2c1a2SKamil Kowalski- public key meets minimal bit length requirement 21138b2c1a2SKamil Kowalski- certificate has to be in it's validity period 21238b2c1a2SKamil Kowalski- notBefore and notAfter fields have to contain valid time 21338b2c1a2SKamil Kowalski- has to be properly signed by certificate authority 21438b2c1a2SKamil Kowalski- certificate cannot be revoked 21538b2c1a2SKamil Kowalski- certificate is well-formed according to X.509 21638b2c1a2SKamil Kowalski- certificate cannot be self-signed 21738b2c1a2SKamil Kowalski- issuer name has to match CA's subject name 21838b2c1a2SKamil Kowalski 21938b2c1a2SKamil KowalskiAfter these checks a callback is invoked providing result of user<->CA matching 220*f4febd00SPatrick Williamsstatus. There, in case of success Redfish extracts username from `CommonName` 22138b2c1a2SKamil Kowalskiand verifies if user does exist in the system. 22238b2c1a2SKamil Kowalski 22338b2c1a2SKamil KowalskiAs can be seen on the flow diagram, Redfish will use **the first valid** 22438b2c1a2SKamil Kowalskicredentials according to processing sequence. It is recommended for user to use 22538b2c1a2SKamil Kowalskionly one set of credentials/authentication data in a single request to be sure 22638b2c1a2SKamil Kowalskiwhat will be used, otherwise there is no certainty which credential are used 22738b2c1a2SKamil Kowalskiduring operation. 22838b2c1a2SKamil Kowalski 229*f4febd00SPatrick WilliamsUser can configure which methods are available in `/redfish/v1/AccountService` 230*f4febd00SPatrick WilliamsOEM schema. The sequence of credential verification stays the same regardless of 231*f4febd00SPatrick Williamsconfiguration. Whitelist verification is always-on, because of Redfish 23238b2c1a2SKamil Kowalskispecification and other accessibility requirements. 23338b2c1a2SKamil Kowalski 23438b2c1a2SKamil KowalskiUser certificate does not have to be signed by the exact CAs whose certificates 23538b2c1a2SKamil Kowalskiare stored, but instead it can be done in a chain (Redfish guarantees support 23638b2c1a2SKamil Kowalskifor chain depth up to 5, but greater ones may work as well). It is recommended 23738b2c1a2SKamil Kowalskito use at least 2048bit RSA or 256/384bit elliptic curve keys. Certificate has 23838b2c1a2SKamil Kowalskito be in its validity period in the moment of session initialization. 23938b2c1a2SKamil Kowalski 24038b2c1a2SKamil Kowalski#### Authorization 24138b2c1a2SKamil Kowalski 24238b2c1a2SKamil KowalskiUser identified by any of methods described above, goes through process of 24338b2c1a2SKamil Kowalskiexamining whether user actually exists, and what privileges, groups, etc. should 24438b2c1a2SKamil Kowalskibe provided. Current base is BasicAuth as it should be used for creating 24538b2c1a2SKamil Kowalskisessions which can be used in following connections, and it is executed by 24638b2c1a2SKamil KowalskiBMCWeb through PAM library usage. Other auth methods have access only to user's 24738b2c1a2SKamil Kowalskilogin credentials without password, so verification of user existence cannot be 24838b2c1a2SKamil Kowalskidirectly done through classic PAM flow, and should be done in other way. This 24938b2c1a2SKamil Kowalskialso applies for certificate based auth, so all non BasicAuth methods should 25038b2c1a2SKamil Kowalskiverify whether user exists and is not locked out of the system on any login 25138b2c1a2SKamil Kowalskiattempt. 25238b2c1a2SKamil Kowalski 25338b2c1a2SKamil Kowalski## Alternatives Considered 25438b2c1a2SKamil Kowalski 25538b2c1a2SKamil KowalskiNone. 25638b2c1a2SKamil Kowalski 25738b2c1a2SKamil Kowalski## Impacts 25838b2c1a2SKamil Kowalski 25938b2c1a2SKamil KowalskiCurrent auth methods will not be impacted. This proposition is based on locally 26038b2c1a2SKamil Kowalskistored CA certificates, so it does not guarantee automated measures against 26138b2c1a2SKamil Kowalskisituations where certificates have been revoked, and user/admin has not yet 26238b2c1a2SKamil Kowalskiupdated certificates on BMC. 26338b2c1a2SKamil Kowalski 26438b2c1a2SKamil Kowalski## Testing 26538b2c1a2SKamil Kowalski 26638b2c1a2SKamil KowalskiTesting should be conducted on currently supported auth methods beside TLS, to 26738b2c1a2SKamil Kowalskiconfirm that their behavior did not change, and did not suffer any regression. 26838b2c1a2SKamil Kowalski 26938b2c1a2SKamil KowalskiAs for TLS auth itself: 270*f4febd00SPatrick Williams 271*f4febd00SPatrick Williams1. Flow described in [Process overview](###process-overview) should be tested, 272*f4febd00SPatrick Williams to confirm that after going through it, everything works as expected. 27338b2c1a2SKamil Kowalski2. Validity period tests - to confirm that certificates that are not-yet-valid 27438b2c1a2SKamil Kowalski and expired ones are not accepted, by both - changing validity periods in 27538b2c1a2SKamil Kowalski certificates themselves, as well as modifying time on BMC itself 27638b2c1a2SKamil Kowalski3. Removing CA certificate and confirming that user will not be granted access 27738b2c1a2SKamil Kowalski after that when using certificate that worked before removal. 27838b2c1a2SKamil Kowalski4. Chain certificates verification - checking that chained certificates are 27938b2c1a2SKamil Kowalski accepted as required. 28038b2c1a2SKamil Kowalski5. Negative tests for breaking user's certificate - invalid username, invalid 28138b2c1a2SKamil Kowalski validity period, invalid CA, binary broken certificate, etc. 282