Create security documentation in docs/security
This creates the openbmc/docs/security directory with files:
- ../README.md -- links to security/README.md
- README.md -- explains the security documentation
- obmc-development-practices.md -- The OpenBMC team
- obmc-downstream-best-practices.md -- BMC lifecycle topics
- obmc-release-checklist.md -- release planning
As explained in the README, two more stories complete the overall
security picture and are being worked on:
- functional security describes what the BMC does to protect itself
in terms of security features and user interfaces
Resolves: openbmc/openbmc #3247.
Change-Id: Ie47038af4939a28646c33ea653bccff0d722ab12
Signed-off-by: Joseph Reynolds <jrey@us.ibm.com>
diff --git a/README.md b/README.md
index 77d47f1..20ff216 100644
--- a/README.md
+++ b/README.md
@@ -36,6 +36,8 @@
- [REST-cheatsheet.md](REST-cheatsheet.md): Quick reference for some common
curl commands usage.
+ - [Security](security/README.md): Root of the security documentation
+
OpenBMC Goals
-------------
diff --git a/security/README.md b/security/README.md
new file mode 100644
index 0000000..190d84a
--- /dev/null
+++ b/security/README.md
@@ -0,0 +1,62 @@
+# OpenBMC security documentation
+
+This is the root of OpenBMC security documentation.
+
+The audience is the OpenBMC development team, projects that use
+OpenBMC, and IT security professionals. Readers are assumed to have
+general familiarity with the firmware development process and with
+OpenBMC's capabilities.
+
+Security is broadly defined to mean avoiding negative impacts to the
+confidentiality, integrity, and availability of the BMC's resources.
+Resources include information stored by the BMC and its capability to
+control itself and its host server.
+
+
+## Security documentation stories
+
+The documentation begins with stories that parallel OpenBMC
+development activities. The stories capture the essence of each
+activity, identify security risks, and explain how OpenBMC addresses
+those risks. Conceptually, all other security work is rooted in these
+stories.
+
+The content and depth of the information presented here is primarily
+intended to foster the development of secure OpenBMC implementations.
+It may also be useful in formal security evaluation processes such as
+[Common Criteria](https://www.commoncriteriaportal.org/).
+
+ - [OpenBMC Server Security Architecture](obmc-securityarchitecture.md).
+ This describes OpenBMC's security features including what OpenBMC does
+ to protect the BMC against security threats. Features include user
+ authentication, transport level security, and secure boot. Example
+ components include:
+ - the BMC and devices such as switches, sensors, and the host
+ - IPMI and the IPMI server
+ - network interfaces, web, and REST API servers
+
+ - [OpenBMC development team security practices](obmc-development-practices.md).
+ This highlights specific practices the development team uses to help
+ ensure only reliable, reviewed, tested code goes into the OpenBMC
+ project. Example topics include:
+ - work items and work flows
+ - repository maintainers and the code review process
+ - use of external servers such as GitHub, Gerrit, and Jenkins
+
+ - [OpenBMC downstream security best practices](obmc-downstream-best-practices.md).
+ This talks about how to protect the BMC from security threats that
+ develop over its lifecycle spanning firmware development, building the
+ install image, provisioning, operation, and decommissioning. Example
+ topics include:
+ - retrieving and configuring OpenBMC and its upstream projects
+ - building an OpenBMC install image
+ - provisioning and operating the BMC
+
+
+## Security work flow
+
+The OpenBMC team has established the following processes:
+
+ - [OpenBMC release planning security checklist](obmc-release-checklist.md).
+ This is a checklist of security work items for OpenBMC release
+ planning.
diff --git a/security/obmc-development-practices.md b/security/obmc-development-practices.md
new file mode 100644
index 0000000..85990c4
--- /dev/null
+++ b/security/obmc-development-practices.md
@@ -0,0 +1,190 @@
+# OpenBMC development team security practices
+
+This document addresses security risks that can be introduced during
+the OpenBMC development process.
+
+The reader is assumed to be familiar with the OpenBMC [contributing
+guidelines](https://github.com/openbmc/docs/blob/master/contributing.md).
+which gives guidelines for coding, testing, and reviewing changes
+to merge into the project.
+
+
+## Open source contributions
+
+OpenBMC is open source. All source code is available to the public
+and anyone can submit changes to a review process which results in
+accepting or abandoning the change.
+
+
+## Code review process
+
+Code reviews are conducted as described in the contributing guidelines
+and are only accepted (merged) when a maintainer is satisfied with the
+quality of the change.
+
+The Gerrit review tool helps provide high quality reviews in the form
+of comments to be seen by all reviewers in context, for re-worked
+material to be seen in context with previous versions, etc.
+
+
+## Maintainers
+
+As described in the [contributing guidelines](https://github.com/openbmc/docs/blob/master/contributing.md),
+the project maintainers are responsible for maintaining the quality
+and integrity and therefore the security of the project.
+
+The [maintainer workflow](../maintainer-workflow.md) describes the
+steps maintainers are expected to take before accepting changes.
+
+Maintainers are expected to maintain secure development environments.
+
+
+## Secure development environments
+
+A secure development environment is broadly defined as one where only
+the intended developers have access to resources including hardware,
+network, storage, command-line and web interfaces. The idea is to
+protect the confidentiality and integrity of the environment.
+
+Secure environments are the basis for securely performing tasks such
+as code reviews, merging code into the master repositories, building,
+and testing code. These tasks are performed by the OpenBMC team as
+part of its quality assurance work.
+
+
+## Development team education
+
+Developers are expected to have basic software development skills
+including open source participation skills. OpenBMC-specific
+education is provided in the docs repository and continues in the form
+of code reviews and communication channels.
+
+The maintainers generally also have formal education in software or
+firmware engineering and keep up with evolving security practices.
+
+Here is security specific education for OpenBMC and upstream projects:
+ - [OpenBMC security](https://github.com/openbmc/openbmc/security)
+ - [Yocto security](https://wiki.yoctoproject.org/wiki/Security)
+ - [OpenSSH security](https://www.openssh.com/security.html)
+
+
+## OpenBMC repository updates
+
+Each OpenBMC repository accepts changes (in the form of git commits)
+only from the maintainers it is configured to accept, and that list is
+controlled by the repository maintainer.
+
+The Gerrit commits are merged into the OpenBMC repositories using
+git's fast-forward merge strategy which avoids merge conflicts. Any
+commits with merge conflicts must be reworked (`git rebase`) before
+they are merged.
+
+Gerrit commit messages can include a "resolves" line which identifies
+an OpenBMC GitHub issue to close when the Gerrit commit is merged.
+
+See the [maintainer workflow](../maintainer-workflow.md) for other
+ways openbmc repositories can be updated.
+
+
+## Use of open source projects and toolchains
+
+The OpenBMC build process pulls in other open source projects,
+including Yocto, OpenEmbedded, and many others. The exact list
+depends on how the downstream developer configured OpenBMC to build.
+(The exact list can be found by using the `bitbake -e` command).
+
+The quality of these projects matters because they can introduce
+security vulnerabilities into the OpenBMC project. The open source
+packages are from well-known sources, specific releases are used, and
+the cryptographic hashes are obtained from trusted sources and
+validated during the build process. All such hashes are stored in the
+OpenBMC build repository (https://github.com/openbmc/openbmc, or as
+cloned) as Bitbake SRCREV variables. This mechanism can control the
+exact set of packages OpenBMC retrieves.
+
+The OpenBMC development team reviews the packages it uses for known
+security vulnerabilities, and updates accordingly.
+
+
+## External development tools
+
+OpenBMC relies on web-based tools such as Gerrit, Jenkins, and Github
+to provide their own security. OpenBMC developers have administration
+access to these sites protect that access, control the site's
+configuration, and rely on the tools to enforce their security
+requirements.
+
+GitHub offers 2-factor authentication (2FA) for user authentication.
+GitHub also offers a way for project owners to require 2FA as a
+prerequisite to edit the project.
+
+OpenBMC relies on the security of the open source gcc-based toolchain,
+including a large set of utility programs. This is also known as the
+Software Development Kit (SDK). These projects are retrieved as
+securely as any other open source project
+
+
+## Work items
+
+Project management uses work items to track features and defects to
+help ensure OpenBMC code is the way it was intended. Specifically,
+work items help identify which security items are merged.
+
+Work items are recorded as Git issues in
+https://github.com/openbmc/openbmc/issues and in other openbmc
+repositories. These generally include defects, features, and wishes.
+Anybody can read, create, and comment on issues. The OpenBMC
+maintainers can assign owners, tag, and close issues.
+
+The responsible disclosure model is to not create public work items
+for high-impact vulnerabilities (easier to reproduce and have larger
+impacts) until a mitigation is available, for example, a tested and
+merged fix.
+
+The Gerrit code review tool also closes github issues when it merges a
+commit that contains a "resolves" line.
+
+
+## Downstream Development
+
+The OpenBMC team produces BMC source code. Apart from a basic test
+suite, it does not build images and it does not provision or maintain
+any BMC.
+
+OpenBMC team members, however, do coordinate with teams that consume
+OpenBMC code and perform these activities. OpenBMC provides guidance
+for such teams in the [OpenBMC downstream security best practices](obmc-downstream-best-practices.md)
+guide.
+
+
+## Test
+
+Testing is a core part of security assurance.
+
+OpenBMC functional test cases are part of the "getting started" guide
+an in each repository. In addition, a Jenkins server at
+https://openpower.xyz runs a continuous integration test which
+compiles, starts up a QEMU-based BMC, and runs a test suite against
+Gerrit-based changes.
+
+The Gerrit code review process invokes a Jenkins-based [continuous
+integration](https://github.com/openbmc/openbmc/wiki/Continuous-Integration)
+server which validates the quality of C++ and Python code (formatting
+rules, etc.) via `clang` and `pycodestyle` and reports its finding
+back to the code review process.
+
+The OpenBMC team has an active community including downstream
+development teams that use OpenBMC and submit work items and fixes
+back into the OpenBMC project, including security items.
+
+Not all OpenBMC configurations are tested.
+
+
+## Release
+
+The OpenBMC project is planning regular releases to begin in 2019 and
+continuing twice per year following the [Yocto project release
+schedule](https://wiki.yoctoproject.org/wiki/Planning).
+
+The [OpenBMC release planning security checklist](obmc-release-checklist.md)
+has work items that should be performed each release.
diff --git a/security/obmc-downstream-best-practices.md b/security/obmc-downstream-best-practices.md
new file mode 100644
index 0000000..63e15cf
--- /dev/null
+++ b/security/obmc-downstream-best-practices.md
@@ -0,0 +1,193 @@
+# OpenBMC downstream security best practices
+
+This describes how to use OpenBMC in projects intended for higher
+security applications. Specifically, this addresses security risks
+that can be introduced throughout the project's lifecycle spanning
+development, build, provisioning, operation, and decommissioning.
+
+Readers are assumed to be familiar with the tasks of developing and
+using OpenBMC, described in [Setting up your OpenBMC
+project](https://github.com/openbmc/openbmc/blob/master/README.md) and
+[OpenBMC Documentation](https://github.com/openbmc/docs).
+
+The [OpenBMC development team security practices](obmc-development-practices.md)
+document describes security practices specific to OpenBMC that also
+may apply to downstream development teams and should be followed.
+
+
+## Development team practices
+
+The [OpenBMC team development security practices](obmc-development-practices.md)
+are used to develop OpenBMC, and similar practices should be used by
+teams who use OpenBMC. In particular, you should have secure
+environments for development and at the BMC operational site.
+
+
+## Obtain source code
+
+You should securely retrieve all the source code you need to build
+OpenBMC, including various openbmc repositories and its upstream
+projects.
+
+A typical development environment would fork stable branches and
+populate private mirror sites.
+
+Consider that the set of packages you need is controlled by your exact
+configuration, including the TEMPLATECONF variable and how your Bitbake
+layers and Bitbake recipes are set up.
+
+
+## Modify and Configure
+
+Here are some considerations when adapting OpenBMC code for your
+application.
+
+Ensure the Bitbake build process retrieves code only from your secure
+environment (repositories and mirrors).
+
+Ensure the Bitbake build process retrieves the code you modified (and
+not an older version) by setting the SRC_URI and SRCREV variables in
+your Bitbake recipes to the versions you intend.
+
+Implement security advice from the Yocto project, including:
+ - the [Yocto security page](https://wiki.yoctoproject.org/wiki/Security)
+ - the [Yocto meta-security layer](https://git.yoctoproject.org/cgit/cgit.cgi/meta-security/about/)
+ - section [Making Images More Secure](https://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html#making-images-more-secure)
+ in the [Yocto Project Development Tasks Manual](https://www.yoctoproject.org/docs/current/dev-manual/dev-manual.html).
+
+The Yocto security topics include:
+ - setting root passwords and creating additional users
+ - turning off debug modes
+ - turning off unneeded services
+ - tightening Linux configuration settings
+ - configuring SELinux Mandatory Access Control (MAC)
+
+Consider the security advice for every upstream project OpenBMC uses.
+
+Configure OpenBMC recipes to use only the elements you need.
+
+Review OpenBMC configuration items, including:
+ - The systemd configuration.
+ - The nginx reverse proxy server
+ - The ipmid IPMI server
+ - The net-impid server
+ - The sshd server
+ - The REST API server
+
+The BMC hardware may have features with security related implications
+that should be taken into consideration when creating a firmware
+distribution because they increase the attack surface of the BMC.
+These are identified in the [OpenBMC Server Security Architecture](obmc-securityarchitecture.md)
+and are specific to the hardware model, for example ASPEED AST2500 or
+Nuvoton W83795 series. Example items include:
+ - disable unneeded bridges between the BMC and host server
+ - disable debug or trace modes
+
+Configure the build process to digitally sign firmware images. Note
+that a build may result in multiple firmware images (UBI and static)
+in different formats (compressed, etc.).
+
+Consider configuring the build to use compiler security hardening
+flags to protect against some kinds of vulnerabilities.
+
+
+## Build
+
+Consider performing the build process in a restricted environment to
+protect the firmware image's integrity before it is signed and to
+protect access to your signing capability.
+
+Have a way to identify the exact version of the code you are building
+so you can re-build from that same version plus fixes.
+
+Consider that the Yocto project does not guarantee 100% reproducible
+images. That means images built from identical source may differ.
+
+Ensure the source tree is clean before building. For example,
+validate that the `git status` command shows no modified files. One
+way to do this is to start from a clean directory and clone the
+openbmc repository.
+
+Consider that the Yocto project does not guarantee 100% reproducible
+images. That means images built from identical source may differ.
+
+Digitally sign the firmware images.
+
+
+## Provisioning
+
+Provisioning includes obtaining hardware and preparing it for
+operation, including installing firmware, post install configuration
+(if needed), and testing.
+
+Have a way for the installer to validate that the BMC install image
+has not been modified. For example, digitally sign the install image
+and publish the public key in a secure area such as a website using
+https, then establish a process to validate the install image
+signature.
+
+BMC hardware should be obtained from reputable sources and prepared
+according to the manufacturer's instructions. Especially consider
+disabling unused functions and applying security measures.
+
+If the host is not trusted (for example, when it is configured as a
+bare-metal server and allowed to have untrusted software or BIOS),
+consider configuring the BMC to limit communication between the host
+and BMC. For example, by only allowing white-listed IPMI commands.
+
+OpenBMC offers several ways to update its firmware. These are
+described in the [OpenBMC code-update docs](https://github.com/openbmc/docs/tree/master/code-update).
+
+OpenBMC offers two build image layouts: UBI and static. With either
+layout, an update can be performed from the OpenBMC's Linux command
+line or from its REST API at URI `/xyz/openbmc_project/software/`.
+
+
+## Operate
+
+Many aspects of operational security are covered by the [OpenBMC
+Server Security Architecture](obmc-securityarchitecture.md) and are
+not repeated here. Example topics include authentication,
+authorization, and accountability such as auditing. Example
+interfaces include REST APIs, web application, and SSH signons.
+
+The security architecture document also makes explicit security
+assumptions in the form of non-goals. Carefully consider each of
+them. To provide security, the operating environment must address
+these. Examples:
+ - The OpenBMC code is not designed to withstand attacks from the
+ internet. The recommendation is to use OpenBMC on private, secure,
+ monitored networks for higher security applications.
+ - OpenBMC offers limited physical security features. Physical security
+ can be provided by some other means, for example, by being in a
+ physically secured data center with controlled access.
+ - Access the BMC's function may provided by IPMI over SMBus (IPMB) by
+ unauthenticated agents.
+
+
+## Repair
+
+Repair refers to the BMC's ability to update its firmware to either
+repair a corrupted image or to install a new version that corrects
+flaws. It does not refer to correcting the firmware of its host
+computer: that is covered by the BMC's operation.
+
+OpenBMC offers ways to update its overall firmware image as discussed
+in the provisioning topic above. OpenBMC does not offer a way to
+patch its firmware image. Operations such as modifying a
+configuration file or replacing a Linux program are not supported.
+
+Diagnostic data. OpenBMC collects data about its operation in the
+form of log files written by various Linux services. These may be
+requested by repair personnel performing diagnostic services. Note
+that they may contain sensitive information.
+
+
+## Decommission
+
+The OpenBMC firmware may store data that should not be disclosed after
+the BMC is removed from service. For example, access credentials and
+information about the host.
+
+The OpenBMC REST API has interfaces to erase some of this data, for
+example, logs, dumps, and firmware images.
diff --git a/security/obmc-release-checklist.md b/security/obmc-release-checklist.md
new file mode 100644
index 0000000..2b2d0fd
--- /dev/null
+++ b/security/obmc-release-checklist.md
@@ -0,0 +1,25 @@
+# OpenBMC release planning security checklist
+
+This is a list of security work items for OpenBMC release planning.
+The idea is to work through this list at least once per release.
+
+Checklist items:
+ 1. Read through the security docs, identify applicable items, and
+ perform them. (This item is a place-holder.)
+
+Ideas:
+ - Create work items for the release's security goals.
+ - Identify vulnerabilities that were caused by OpenBMC code and
+ document them (preferably as CVEs) along with their mitigation .
+ - Compile the list of OpenBMC's upstream packages (or one list per
+ configuration?) and document each package along with a link to its
+ security info (such as the CVEs the new release fixed).
+ - Update OpenBMC (bitbake recipes) to retrieve newer upstream
+ packages that fix security vulnerabilities.
+ - Perform security testing (with selected configurations).
+ - Perform static code analysis.
+ - Review project configuration items such as:
+ + GitHub/repo owners and maintainers: has someone left the
+ project?
+ + Jenkins and Gerrit server authorizations
+ + Remove obsolete repositories