diff options
author | Patrick Williams <patrick@stwcx.xyz> | 2022-12-07 16:43:50 +0300 |
---|---|---|
committer | Patrick Williams <patrick@stwcx.xyz> | 2022-12-07 16:43:50 +0300 |
commit | f4f2643ae8aa4a6e8f8db62a7e0377a8f222c3f9 (patch) | |
tree | 4aa50c1dfe42dc4f1ec58dcc176f95f5d057855a /DEVELOPING.md | |
parent | dfa3fdc3dc1045babc67ecd7974c4d997006d9c4 (diff) | |
download | bmcweb-f4f2643ae8aa4a6e8f8db62a7e0377a8f222c3f9.tar.xz |
markdownlint: fix all warnings
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: I1402cbd84c916792ca2fc0ad0f34db661cbdfa72
Diffstat (limited to 'DEVELOPING.md')
-rw-r--r-- | DEVELOPING.md | 248 |
1 files changed, 125 insertions, 123 deletions
diff --git a/DEVELOPING.md b/DEVELOPING.md index d475d5364d..77cfeceadf 100644 --- a/DEVELOPING.md +++ b/DEVELOPING.md @@ -1,150 +1,151 @@ # OpenBMC Webserver Development -1. ### Performance targets +## Guidelines - As OpenBMC is intended to be deployed on an embedded system, care should be - taken to avoid expensive constructs, and memory usage. In general, our - performance and metric targets are: +### Performance targets - - Binaries and static files should take up < 1MB of filesystem size - - Memory usage should remain below 10MB at all times - - Application startup time should be less than 1 second on target hardware - (AST2500) - -2. ### Asynchronous programming - - Care should be taken to ensure that all code is written to be asynchronous in - nature, to avoid blocking methods from stopping the processing of other - tasks. At this time the webserver uses boost::asio for it async framework. - Threads should be avoided if possible, and instead use async tasks within - boost::asio. - -3. ### Secure coding guidelines - - Secure coding practices should be followed in all places in the webserver +As OpenBMC is intended to be deployed on an embedded system, care should be +taken to avoid expensive constructs, and memory usage. In general, our +performance and metric targets are: - In general, this means: - - - All buffer boundaries must be checked before indexing or using values - - All pointers and iterators must be checked for null before dereferencing - - All input from outside the application is considered untrusted, and should - be escaped, authorized and filtered accordingly. This includes files in the - filesystem. - - All error statuses are checked and accounted for in control flow. - - Where applicable, noexcept methods should be preferred to methods that use - exceptions - - Explicitly bounded types should be preferred over implicitly bounded types - (like std::array<int, size> as opposed to int[size]) - - no use of - [Banned functions](https://github.com/intel/safestringlib/wiki/SDL-List-of-Banned-Functions "Banned function list") +- Binaries and static files should take up < 1MB of filesystem size +- Memory usage should remain below 10MB at all times +- Application startup time should be less than 1 second on target hardware + (AST2500) -4. ### Error handling - - Error handling should be constructed in such a way that all possible errors - return valid HTTP responses. The following HTTP codes will be used commonly +### Asynchronous programming - - 200 OK - Request was properly handled - - 201 Created - Resource was created - - 401 Unauthorized - Request didn't posses the necessary authentication - - 403 Forbidden - Request was authenticated, but did not have the necessary - permissions to accomplish the requested task - - 404 Not found - The url was not found - - 500 Internal error - Something has broken within the OpenBMC web server, - and should be filed as a bug +Care should be taken to ensure that all code is written to be asynchronous in +nature, to avoid blocking methods from stopping the processing of other tasks. +At this time the webserver uses boost::asio for it async framework. Threads +should be avoided if possible, and instead use async tasks within boost::asio. + +### Secure coding guidelines - Where possible, 307 and 308 redirects should be avoided, as they introduce - the possibility for subtle security bugs. +Secure coding practices should be followed in all places in the webserver -5. ### Startup times +In general, this means: - Given that the most common target of OpenBMC is an ARM11 processor, care - needs to be taken to ensure startup times are low. In general this means: +- All buffer boundaries must be checked before indexing or using values +- All pointers and iterators must be checked for null before dereferencing +- All input from outside the application is considered untrusted, and should be + escaped, authorized and filtered accordingly. This includes files in the + filesystem. +- All error statuses are checked and accounted for in control flow. +- Where applicable, noexcept methods should be preferred to methods that use + exceptions +- Explicitly bounded types should be preferred over implicitly bounded types + (like std::array<int, size> as opposed to int[size]) +- no use of + [Banned functions](https://github.com/intel/safestringlib/wiki/SDL-List-of-Banned-Functions "Banned function list") - - Minimizing the number of files read from disk at startup. Unless a feature - is explicitly intended to be runtime configurable, its logic should be - "baked in" to the application at compile time. For cases where the - implementation is configurable at runtime, the default values should be - included in application code to minimize the use of nonvolatile storage. - - Avoid excessive memory usage and mallocs at startup. +### Error handling -6. ### Compiler features +Error handling should be constructed in such a way that all possible errors +return valid HTTP responses. The following HTTP codes will be used commonly - - At this point in time, the webserver sets a number of security flags in - compile time options to prevent misuse. The specific flags and what - optimization levels they are enabled at are documented in the - CMakeLists.txt file. - - Exceptions are currently enabled for webserver builds, but their use is - discouraged. Long term, the intent is to disable exceptions, so any use of - them for explicit control flow will likely be rejected in code review. Any - use of exceptions should be cases where the program can be reasonably - expected to crash if the exception occurs, as this will be the future - behavior once exceptions are disabled. - - Run time type information is disabled - - Link time optimization is enabled +- 200 OK - Request was properly handled +- 201 Created - Resource was created +- 401 Unauthorized - Request didn't posses the necessary authentication +- 403 Forbidden - Request was authenticated, but did not have the necessary + permissions to accomplish the requested task +- 404 Not found - The url was not found +- 500 Internal error - Something has broken within the OpenBMC web server, and + should be filed as a bug -7. ### Authentication +Where possible, 307 and 308 redirects should be avoided, as they introduce the +possibility for subtle security bugs. - The webserver shall provide the following authentication mechanisms. +### Startup times - - Basic authentication - - Cookie authentication - - Token authentication +Given that the most common target of OpenBMC is an ARM11 processor, care needs +to be taken to ensure startup times are low. In general this means: - There shall be connection between the authentication mechanism used and - resources that are available over it. The webserver shall employ an - authentication scheme that is in line with the rest of OpenBMC, and allows - users and privileges to be provisioned from other interfaces. +- Minimizing the number of files read from disk at startup. Unless a feature is + explicitly intended to be runtime configurable, its logic should be "baked in" + to the application at compile time. For cases where the implementation is + configurable at runtime, the default values should be included in application + code to minimize the use of nonvolatile storage. +- Avoid excessive memory usage and mallocs at startup. -8. ### Web security +### Compiler features - The OpenBMC webserver shall follow the latest OWASP recommendations for - authentication, session management, and security. +- At this point in time, the webserver sets a number of security flags in + compile time options to prevent misuse. The specific flags and what + optimization levels they are enabled at are documented in the CMakeLists.txt + file. +- Exceptions are currently enabled for webserver builds, but their use is + discouraged. Long term, the intent is to disable exceptions, so any use of + them for explicit control flow will likely be rejected in code review. Any use + of exceptions should be cases where the program can be reasonably expected to + crash if the exception occurs, as this will be the future behavior once + exceptions are disabled. +- Run time type information is disabled +- Link time optimization is enabled -9. ### Performance +### Authentication - The performance priorities for the OpenBMC webserver are (in order): +The webserver shall provide the following authentication mechanisms. - 1. Code is readable and clear - 2. Code follows secure guidelines - 3. Code is performant, and does not unnecessarily abstract concepts at the - expense of performance - 4. Code does not employ constructs which require continuous system resources, - unless required to meet performance targets. (example: caching sensor - values which are expected to change regularly) +- Basic authentication +- Cookie authentication +- Token authentication -10. ### Abstraction/interfacing - - In general, the OpenBMC webserver is built using the data driven design. - Abstraction and Interface guarantees should be used when multiple - implementations exist, but for implementations where only a single - implementation exists, prefer to make the code correct and clean rather than - implement a concrete interface. +There shall be connection between the authentication mechanism used and +resources that are available over it. The webserver shall employ an +authentication scheme that is in line with the rest of OpenBMC, and allows users +and privileges to be provisioned from other interfaces. -11. ### phosphor webui - - The webserver should be capable of hosting phosphor-webui, and implementing - the required flows to host the application. In general, all access methods - should be available to the webui. - -12. ### Redfish - - bmcweb's Redfish implementation, including Redfish OEM Resources, shall - conform to the Redfish specification. Please keep bmcweb's - [Redfish support document](https://github.com/openbmc/bmcweb/blob/master/Redfish.md) - updated. OEM schemas should conform and be developed in line with the rules - in - [OEM SCHEMAS](https://github.com/openbmc/bmcweb/blob/master/OEM_SCHEMAS.md). +### Web security -13. ### Common errors +The OpenBMC webserver shall follow the latest OWASP recommendations for +authentication, session management, and security. - A number of examples of common errors are captured in the common errors doc. - It is recommended that developers read and understand all of them before - starting any openbmc development. - [Common Errors](https://github.com/openbmc/bmcweb/blob/master/COMMON_ERRORS.md). +### Performance -14. ### Commit messages - Project commit message formatting should be obeyed - [link](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages) +The performance priorities for the OpenBMC webserver are (in order): + +1. Code is readable and clear +2. Code follows secure guidelines +3. Code is performant, and does not unnecessarily abstract concepts at the + expense of performance +4. Code does not employ constructs which require continuous system resources, + unless required to meet performance targets. (example: caching sensor values + which are expected to change regularly) + +### Abstraction/interfacing + +In general, the OpenBMC webserver is built using the data driven design. +Abstraction and Interface guarantees should be used when multiple +implementations exist, but for implementations where only a single +implementation exists, prefer to make the code correct and clean rather than +implement a concrete interface. + +### phosphor webui + +The webserver should be capable of hosting phosphor-webui, and implementing the +required flows to host the application. In general, all access methods should be +available to the webui. + +### Redfish + +bmcweb's Redfish implementation, including Redfish OEM Resources, shall conform +to the Redfish specification. Please keep bmcweb's +[Redfish support document](https://github.com/openbmc/bmcweb/blob/master/Redfish.md) +updated. OEM schemas should conform and be developed in line with the rules in +[OEM SCHEMAS](https://github.com/openbmc/bmcweb/blob/master/OEM_SCHEMAS.md). + +### Common errors + +A number of examples of common errors are captured in the common errors doc. It +is recommended that developers read and understand all of them before starting +any openbmc development. +[Common Errors](https://github.com/openbmc/bmcweb/blob/master/COMMON_ERRORS.md). + +### Commit messages + +Project commit message formatting should be obeyed +[link](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#formatting-commit-messages) Commit messages should answer the following questions: @@ -162,9 +163,10 @@ Commit messages should answer the following questions: Commit messages should be line wrapped 50/72. -15. ### Compatibility - "Don't make your users mad" Greg K-H - [source](https://git.sr.ht/~gregkh/presentation-application_summit/tree/main/keep_users_happy.pdf) +### Compatibility + +> Don't make your users mad - +> [Greg K-H](https://git.sr.ht/~gregkh/presentation-application_summit/tree/main/keep_users_happy.pdf) The kernel has very similar rules around compatibility that we should aspire to follow in the footsteps of. |