1# OpenBMC Webserver Development 2 31. ### Performance targets 4 5 As OpenBMC is intended to be deployed on an embedded system, care should be 6 taken to avoid expensive constructs, and memory usage. In general, our 7 performance and metric targets are: 8 9 - Binaries and static files should take up < 1MB of filesystem size 10 - Memory usage should remain below 10MB at all times 11 - Application startup time should be less than 1 second on target hardware 12 (AST2500) 13 142. ### Asynchronous programming 15 16 Care should be taken to ensure that all code is written to be asynchronous in 17 nature, to avoid blocking methods from stopping the processing of other 18 tasks. At this time the webserver uses boost::asio for it async framework. 19 Threads should be avoided if possible, and instead use async tasks within 20 boost::asio. 21 223. ### Secure coding guidelines 23 24 Secure coding practices should be followed in all places in the webserver 25 26 In general, this means: 27 28 - All buffer boundaries must be checked before indexing or using values 29 - All pointers and iterators must be checked for null before dereferencing 30 - All input from outside the application is considered untrusted, and should 31 be escaped, authorized and filtered accordingly. This includes files in the 32 filesystem. 33 - All error statuses are checked and accounted for in control flow. 34 - Where applicable, noexcept methods should be preferred to methods that use 35 exceptions 36 - Explicitly bounded types should be preferred over implicitly bounded types 37 (like std::array<int, size> as opposed to int[size]) 38 - no use of 39 [Banned functions](https://github.com/intel/safestringlib/wiki/SDL-List-of-Banned-Functions "Banned function list") 40 414. ### Error handling 42 43 Error handling should be constructed in such a way that all possible errors 44 return valid HTTP responses. The following HTTP codes will be used commonly 45 46 - 200 OK - Request was properly handled 47 - 201 Created - Resource was created 48 - 401 Unauthorized - Request didn't posses the necessary authentication 49 - 403 Forbidden - Request was authenticated, but did not have the necessary 50 permissions to accomplish the requested task 51 - 404 Not found - The url was not found 52 - 500 Internal error - Something has broken within the OpenBMC web server, 53 and should be filed as a bug 54 55 Where possible, 307 and 308 redirects should be avoided, as they introduce 56 the possibility for subtle security bugs. 57 585. ### Startup times 59 60 Given that the most common target of OpenBMC is an ARM11 processor, care 61 needs to be taken to ensure startup times are low. In general this means: 62 63 - Minimizing the number of files read from disk at startup. Unless a feature 64 is explicitly intended to be runtime configurable, its logic should be 65 "baked in" to the application at compile time. For cases where the 66 implementation is configurable at runtime, the default values should be 67 included in application code to minimize the use of nonvolatile storage. 68 - Avoid excessive memory usage and mallocs at startup. 69 706. ### Compiler features 71 72 - At this point in time, the webserver sets a number of security flags in 73 compile time options to prevent misuse. The specific flags and what 74 optimization levels they are enabled at are documented in the 75 CMakeLists.txt file. 76 - Exceptions are currently enabled for webserver builds, but their use is 77 discouraged. Long term, the intent is to disable exceptions, so any use of 78 them for explicit control flow will likely be rejected in code review. Any 79 use of exceptions should be cases where the program can be reasonably 80 expected to crash if the exception occurs, as this will be the future 81 behavior once exceptions are disabled. 82 - Run time type information is disabled 83 - Link time optimization is enabled 84 857. ### Authentication 86 87 The webserver shall provide the following authentication mechanisms. 88 89 - Basic authentication 90 - Cookie authentication 91 - Token authentication 92 93 There shall be connection between the authentication mechanism used and 94 resources that are available over it. The webserver shall employ an 95 authentication scheme that is in line with the rest of OpenBMC, and allows 96 users and privileges to be provisioned from other interfaces. 97 988. ### Web security 99 100 The OpenBMC webserver shall follow the latest OWASP recommendations for 101 authentication, session management, and security. 102 1039. ### Performance 104 105 The performance priorities for the OpenBMC webserver are (in order): 106 107 1. Code is readable and clear 108 2. Code follows secure guidelines 109 3. Code is performant, and does not unnecessarily abstract concepts at the 110 expense of performance 111 4. Code does not employ constructs which require continuous system resources, 112 unless required to meet performance targets. (example: caching sensor 113 values which are expected to change regularly) 114 11510. ### Abstraction/interfacing 116 117 In general, the OpenBMC webserver is built using the data driven design. 118 Abstraction and Interface guarantees should be used when multiple 119 implementations exist, but for implementations where only a single 120 implementation exists, prefer to make the code correct and clean rather than 121 implement a concrete interface. 122 12311. ### phosphor webui 124 125 The webserver should be capable of hosting phosphor-webui, and implementing 126 the required flows to host the application. In general, all access methods 127 should be available to the webui. 128 12912. ### Redfish 130 131 bmcweb's Redfish implementation, including Redfish OEM Resources, shall 132 conform to the Redfish specification. Please keep bmcweb's 133 [Redfish support document](https://github.com/openbmc/bmcweb/blob/master/Redfish.md) 134 updated. OEM schemas should conform and be developed in line with the rules 135 in 136 [OEM SCHEMAS](https://github.com/openbmc/bmcweb/blob/master/OEM_SCHEMAS.md). 137 13813. ### Common errors 139 140 A number of examples of common errors are captured in the common errors doc. 141 It is recommended that developers read and understand all of them before 142 starting any openbmc development. 143 [Common Errors](https://github.com/openbmc/bmcweb/blob/master/COMMON_ERRORS.md). 144 14514. ### Commit messages 146 Project commit message formatting should be obeyed 147 [link](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages) 148 149Commit messages should answer the following questions: 150 151- Why are the changes useful? Given that bmcweb is a user-facing daemon, commits 152 adding new functionality should include statements about how the commit in 153 question is useful to the user. 154 155- What changes would a user expect to see? This includes new parameters, new 156 resources, and new or changed properties. Any route changes should be 157 explicitly called out. 158 159- Are there compatibility concerns? Is this change backward compatible for 160 clients? If not, what commit would be broken, and how old is it? Have clients 161 been warned? (ideally on the mailing list) link the discussion. 162 163Commit messages should be line wrapped 50/72. 164 16515. ### Compatibility 166 "Don't make your users mad" Greg K-H 167 [source](https://git.sr.ht/~gregkh/presentation-application_summit/tree/main/keep_users_happy.pdf) 168 169The kernel has very similar rules around compatibility that we should aspire to 170follow in the footsteps of. 171 172To that end, bmcweb will do its' best to insulate clients from breaking api 173changes. Being explicit about this ensures that clients can upgrade their 174OpenBMC version without issue, and resolves a significant bottleneck in getting 175security patches deployed to users. Any change that's visible to a user is 176potentially a breaking change, but requiring _all_ visible changes to be 177configurable would increase the software complexity, therefore bmcweb makes 178exceptions for things which a client is reasonably expected to code against: 179 180- New items added to a collection 181- Changes in UID for hypermedia resources (In line with Redfish spec) 182- New properties added to a resource 183- New versions of a given schema 184 185Special note: Code exists in bmcweb that is missing upstream backends to make it 186function. Given that compatibility requires the ability to use and test the 187feature in question, changes to these methods, including outright removal, does 188not constitute a breaking change. 189 190Security: There may be cases where maintainers make explicit breaking changes in 191the best interest of security; In these rare cases, the maintainers and 192contributors will endeavor to avoid breaking clients as much as is technically 193possible, but as with all security, impact will need to be weighed against the 194security impact of not making changes, and judgement calls will be made, with 195options to allow providing the old behavior. 196 197## clang-tidy 198 199clang-tidy is a tool that can be used to identify coding style violations, bad 200design patterns, and bug prone constructs. The checks are implemented in the 201.clang-tidy file in the root of bmcweb, and are expected to be passing. 202[openbmc-build-scripts](https://github.com/openbmc/openbmc-build-scripts/blob/master/run-unit-test-docker.sh) 203implements clang-tidy checks and is the recommended way to run these checks 204