Add OpenBmc Developing docs

The DEVELOPING file is intended to set expectations and requirements
around the behavior or the OpenBmc webserver.  While not a complete
requirement list, it improves considerably upon the docs previously
available.

Change-Id: I0a7119017133aaf15874f9edab4967650e29dc63
Signed-off-by: Ed Tanous <ed.tanous@intel.com>

1 files changed, 568 insertions, 0 deletions

diff --git a/DEVELOPING.md b/DEVELOPING.md
new file mode 100644
index 0000000000..a51864c124
--- /dev/null
+++ b/DEVELOPING.md
@@ -0,0 +1,568 @@
+#OpenBMC Webserver Development
+
+1. ### Performance targets
+    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:
+
+    - 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. ### Asyncronous programming
+   Care should be taken to ensure that all code is written to be asyncronous 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
+
+    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")
+
+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
+    - 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
+
+    Where possible, 307 and 308 redirects should be avoided, as they introduce
+    the possibility for subtle security bugs.
+
+
+4. ### Startup times
+   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:
+
+    - 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.
+
+5. ### Compiler features
+    - 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
+
+5. ### Authentication
+   The webserver shall provide the following authentication mechanisms.
+    - Basic authentication
+    - Cookie authentication
+    - Token authentication
+
+    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.
+
+6. ### Web security
+   The OpenBMC webserver shall follow the latest OWASP recommendations for
+   authentication, session management, and security.
+
+7. ### Performance
+   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)
+
+8. ### Abstraction/interfacing
+   In general, the OpenBMC webserver is built using the data driven design.
+   Abstraction and Interface gaurentees 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.
+
+9. ### phosphor webui
+   The webserver should be capable of hosting phosphor-webui, and impelmenting
+   the required flows to host the application.  In general, all access methods
+   should be available to the webui.
+
+10. ### Redfish
+
+The redfish implementation shall pass the [Redfish Service
+Validator](https://github.com/DMTF/Redfish-Service-Validator "Validator") with
+no warnings or errors
+
+The following redfish schemas and fields are targeted for OpenBMC.  This is a
+living document, and these schemas are subject to change.
+
+Fields common to all schemas
+
+- @odata.context
+- @odata.id
+- @odata.type
+- Id
+- Name
+
+
+#### /redfish/v1/
+##### ServiceRoot
+
+- RedfishVersion
+- UUID
+
+#### /redfish/v1/AccountService/
+##### AccountService
+
+- Description
+- ServiceEnabled
+- MinpasswordLength
+- MaxPasswordLength
+- Accounts
+- Roles
+
+#### /redfish/v1/AccountService/Accounts/
+##### AccountCollection
+
+- Description
+- Members@odata.count
+- Members
+
+#### /redfish/v1/AccountService/Accounts/<AccountName>
+##### Account
+
+- Description
+- Enabled
+- Password
+- UserName
+- RoleId
+- Links/Role
+
+#### /redfish/v1/AccountService/Roles/
+##### RoleCollection
+
+- Description
+- Members@odata.count
+- Members
+    - By default will contain 3 roles, "Administrator", "Operator", and "User"
+
+
+#### /redfish/v1/AccountService/Roles/<RoleName>
+##### Role
+
+- Description
+- IsPredefined
+    - Will be set to true for all default roles.  If the given role is
+      non-default, or has been modified from default, will be marked as false.
+- AssignedPrivileges
+    - For the default roles, the following privileges will be assigned by
+      default
+        - Administrator: Login, ConfigureManager, ConfigureUsers, ConfigureSelf,
+          ConfigureComponents
+        - Operator: Login, ConfigureComponents
+        - User: Login
+
+#### /redfish/v1/Chassis
+##### ChassisCollection
+
+- Members@odata.count
+- Members
+
+#### /redfish/v1/Chassis/<ChassisName>
+##### Chassis
+
+- ChassisType
+- Manufacturer
+- Model
+- SerialNumber
+- PartNumber
+- PowerState
+- Thermal
+    - Shall be included if component contains temperature sensors, otherwise
+      shall be omited.
+- Power
+    - Shall be included if component contains voltage/current sensing
+      components, otherwise will be omited.
+
+
+#### /redfish/v1/Chassis/<ChassisName>/Thermal
+##### Thermal
+Temperatures Fans Redundancy
+
+
+#### /redfish/v1/Chassis/<ChassisName>/Thermal#/Temperatures/<SensorName>
+##### Temperature
+- MemberId
+- Status
+- ReadingCelsius
+- UpperThresholdNonCritical
+- UpperThresholdCritical
+- LowerThresholdNonCritical
+- LowerThresholdCritical
+- MinReadingRange
+- MaxReadingRange
+
+*threshold fields only present if defined for sensor, otherwise absent*
+
+#### /redfish/v1/Chassis/<ChassisName>/Thermal#/Fans/<FanName>
+##### Fan
+- MemberId
+- Status
+- Reading
+- ReadingUnits
+- UpperThresholdNonCritical
+- UpperThresholdCritical
+- LowerThresholdNonCritical
+- LowerThresholdCritical
+- MinReadingRange
+- MaxReadingRange
+- Redundancy
+
+*threshold fields only present if defined for sensor, otherwise absent*
+
+#### /redfish/v1/Chassis/<ChassisName>/Thermal#/Redundancy/<RedundancyName>
+##### Fan
+- MemberId
+- RedundancySet
+- Mode
+- Status
+- MinNumNeeded
+- MaxNumSupported
+
+
+#### /redfish/v1/Chassis/<ChassisName>/Power/
+##### Thermal
+PowerControl Voltages PowerSupplies Redundancy
+
+#### /redfish/v1/Chassis/<ChassisName>/Power#/PowerControl/<ControlName>
+##### PowerControl
+- MemberId
+- PowerConsumedWatts
+- PowerMetrics/IntervalInMin
+- PowerMetrics/MinConsumedWatts
+- PowerMetrics/MaxConsumedWatts
+- PowerMetrics/AverageConsumedWatts
+- RelatedItem
+    - Should list systems and related chassis
+
+
+#### /redfish/v1/Chassis/<ChassisName>/Power#/Voltages/<VoltageName>
+##### Voltage
+- MemberId
+- Status
+- ReadingVolts
+- UpperThresholdNonCritical
+- UpperThresholdCritical
+- LowerThresholdNonCritical
+- LowerThresholdCritical
+- MinReadingRange
+- MaxReadingRange
+- PhysicalContext
+- RelatedItem
+
+#### /redfish/v1/Chassis/<ChassisName>/Power#/PowerSupplies/<PSUName>
+##### PowerSupply
+- MemberId
+- Status
+- LininputVoltage
+- Model
+- manufacturer
+- FirmwareVersion
+- SerialNumber
+- PartNumber
+- RelatedItem
+- Redundancy
+
+#### /redfish/v1/Chassis/{ChassisName}/Power#/Redundancy/<RedundancyName>
+##### Redundancy
+- MemberId
+- RedundancySet
+- Mode
+- Status
+- MinNumNeeded
+- MaxNumSupported
+
+
+#### /redfish/v1/EventService
+##### EventService
+- Id
+- ServiceEnabled
+- DeliveryRetryAttempts
+    - Defaults to 3
+- EventTypesForSubscription
+    - Defaults to "Alert"
+- Actions
+- Subscriptions
+
+#### /redfish/v1/EventService/Subscriptions
+##### EventDestinationCollection
+- Members@odata.count
+- Members
+
+#### /redfish/v1/EventService/Subscriptions/{EventName}/
+##### EventDestination
+- Id
+- Destination
+- EventTypes
+- Context
+- OriginResources
+- Protocol
+
+#### /redfish/v1/Managers
+##### ManagerCollection
+- Members
+- Members@odata.count
+
+#### /redfish/v1/Managers/BMC
+##### Manager
+- Description
+- LogServices
+- GraphicalConsole
+- UUID
+- Model
+- Links
+- PowerState
+- FirmwareVersion
+- ManagerType
+- ServiceEntryPointUUID
+- DateTime
+- NetworkProtocol
+- Actions
+- Status
+- SerialConsole
+- VirtualMedia
+- EthernetInterfaces
+
+#### /redfish/v1/Managers/BMC/EthernetInterfaces
+##### EthernetInterfaceCollection
+- Members
+- Members@odata.count
+- Description
+
+#### /redfish/v1/Managers/BMC/EthernetInterfaces/{InterfaceName}
+##### EthernetInterface
+- Description
+- VLAN
+- MaxIPv6StaticAddresses
+
+#### /redfish/v1/Managers/BMC/LogServices
+##### LogServiceCollection
+- Members
+- Members@odata.count
+- Description
+
+#### /redfish/v1/Managers/BMC/LogServices/RedfishLog
+##### LogService
+- Entries
+- OverWritePolicy
+- Actions
+- Status
+- DateTime
+- MaxNumberOfRecords
+
+#### /redfish/v1/Managers/BMC/LogServices/RedfishLog/Entries/{entry}
+##### LogEntry
+- Message
+- Created
+- EntryType
+
+#### /redfish/v1/Managers/BMC/NetworkProtocol
+##### ManagerNetworkProtocol
+- Description
+- SSDP
+- HTTPS
+- SSH
+- VirtualMedia
+- KVMIP
+- Status
+
+#### /redfish/v1/Registries
+##### MessageRegistryFileCollection
+- Members
+    - Should support Base, CommonMessages, and EventingMessages
+- Members@odata.count
+- Description
+
+#### /redfish/v1/Registries/<MessageRegistry>
+##### MessageRegistryFile
+- Location
+- Description
+- Location@odata.count
+- Languages@odata.count
+- Languages
+- Registry
+
+#### /redfish/v1/SessionService
+##### SessionService
+- Description
+- ServiceEnabled
+- Status
+- SessionTimeout
+- Sessions
+
+#### /redfish/v1/SessionService/Sessions
+##### SessionCollection
+- Members
+- Members@odata.count
+- Description
+
+#### /redfish/v1/Systems
+##### ComputerSystemCollection
+- Members
+    - Should support one system
+- Members@odata.count
+
+#### /redfish/v1/Systems/{SystemName}
+##### ComputerSystem
+- Boot
+- PartNumber
+- IndicatorLED
+- UUID
+- LogServices
+- SystemType
+- Manufacturer
+- Description
+- Model
+- Links
+- PowerState
+- BiosVersion
+- Storage
+- SerialNumber
+- Processors
+- ProcessorSummary
+- Memory
+- Actions
+- Status
+- EthernetInterfaces
+- MemorySummary
+
+#### /redfish/v1/Systems/{SystemName}/EthernetInterfaces
+##### EthernetInterfaceCollection
+- Members
+- Members@odata.count
+- Description
+
+#### /redfish/v1/Systems/{SystemName}/LogServices
+##### LogServiceCollection
+- Members
+    - Should default to one member, named SEL
+- Members@odata.count
+- Description
+
+#### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries
+##### LogEntryCollection
+- Members
+- Members@odata.count
+- Description
+- @odata.nextLink
+
+#### /redfish/v1/Systems/{SystemName}/LogServices/SEL/Entries/{entryNumber}
+##### LogEntry
+- MessageArgs
+- Severity
+- SensorType
+- Message
+- MessageId
+- Created
+- EntryCode
+- EntryType
+
+#### /redfish/v1/Systems/{SystemName}/Memory
+##### MemoryCollection
+- Members
+- Members@odata.count
+
+#### /redfish/v1/Systems/{SystemName}/Memory/Memory1
+##### Memory
+- MemoryType
+- Description
+- DeviceLocator
+- Oem
+- Metrics
+- BaseModuleType
+- Manufacturer
+- MemoryDeviceType
+- RankCount
+- AllowedSpeedsMHz
+- CapacityMiB
+- DataWidthBits
+- SerialNumber
+- OperatingSpeedMhz
+- ErrorCorrection
+- PartNumber
+- Status
+- BusWidthBits
+- MemoryMedia
+
+#### /redfish/v1/Systems/{SystemName}/Memory/Memory1/MemoryMetrics
+##### MemoryMetrics
+- Description
+- HealthData
+
+#### /redfish/v1/Systems/{SystemName}/Processors
+##### ProcessorCollection
+- Members
+    - Should Support CPU1 and CPU2 for dual socket systems
+- Members@odata.count
+
+#### /redfish/v1/Systems/{SystemName}/Processors/{CPUName}
+##### Processor
+- ProcessorArchitecture
+- TotalCores
+- ProcessorId
+- MaxSpeedMHz
+- Manufacturer
+- Status
+- Socket
+- InstructionSet
+- Model
+- ProcessorType
+- TotalThreads
+
+#### /redfish/v1/Systems/{SystemName}/Storage
+##### StorageCollection
+- Members
+- Members@odata.count
+  #### /redfish/v1/Systems/{SystemName}/Storage/{storageIndex>
+##### Storage
+- Drives
+- Links
+
+#### /redfish/v1/UpdateService
+##### UpdateService
+- SoftwareInventory
+  #### /redfish/v1/UpdateService/SoftwareInventory
+##### SoftwareInventoryCollection
+- Members
+- Should Support BMC, ME, CPLD and BIOS
+- Members@odata.count
+  #### /redfish/v1/UpdateService/SoftwareInventory/{MemberName}
+##### SoftwareInventory
+- Version