Incident reporting: clarify the role of the OP-TEE project

We have recently had a couple of security incidents being reported to
the OP-TEE project. With these reports it's clear that there is a need
to clarify the role of the OP-TEE project as well as adding some extra
pointers to the vulnerability reporting.

All in all it boils down to that the OP-TEE project serves as a
reference implementation for developers and device manufacturers. A
consequence of using a reference implementation is that the one using it
in end products must understand that there are certain changes that
needs to be done for the final product. These changes are not always
available nor applicable in the vanilla and default OP-TEE reference
implementation.

It is important to understand that for two reasons. First is to make
sure that the end product is configured to be secure. The second reason
is that when there are security issues, the issue might, or might not be
applicable in the OP-TEE reference implementation, in the platform code
or in some cases just in a particular device or in a mix of all of them.
Hence the reporter should give an extra thought regarding that before
filing a security report.

Signed-off-by: Joakim Bech <joakim.bech@linaro.org>
Reviewed-by: Jens Wiklander <jens.wiklander@linaro.org>
Reviewed-by: Ruchika Gupta <ruchika.gupta@linaro.org>

architecture/porting_guidelines.rst

@@ -392,6 +392,28 @@ limited since we only support a single key which is used for all TA's. We have
 plans on extending this to make it a bit more flexible. Exactly when that will
 happen has not been decided yet.
 
+.. _platform_ports:
+
+Platform ports
+**************
+OP-TEE is a reference implementation for developers and device manufacturers.
+This also implies that there are certain configurations and settings that cannot
+be done in OP-TEE reference code. In short, there are cases when the default
+configuration hasn't enabled all necessary security features for the end
+product. There are a couple of reasons for that.
+
+- Chipmakers and Semiconductors might only share specifications telling how to
+  securely configure their devices with partners who have signed an NDA with
+  them.
+- In some cases a setting might be perfectly fine when OP-TEE is used in one
+  particular environment, but the same setting might be insecure in another
+  environment.
+
+Because of this we always urge companies and device manufacturers making the end
+product to follow the security guidelines from the chipmaker they are basing
+their products on.
+
+
 .. _core/arch/arm/plat-hikey/conf.mk: https://github.com/OP-TEE/optee_os/blob/master/core/arch/arm/plat-hikey/conf.mk
 .. _core/include/crypto/crypto.h: https://github.com/OP-TEE/optee_os/blob/master/core/include/crypto/crypto.h
 .. _core/include/kernel/tee_common_otp.h: https://github.com/OP-TEE/optee_os/blob/master/core/include/kernel/tee_common_otp.h

general/contact.rst

@@ -50,6 +50,22 @@ security incident process as described at the `TrustedFirmware.org security inci
 page. To report an issue, please follow the process as specified here. The email
 address to use can be found at the `Mailing Aliases`_ page.
 
+Note that OP-TEE is a reference implementation for developers and device
+manufacturers and by being a reference implementation it is not always running a
+secure device configuration by default (see :ref:`platform_ports` for more
+information). Therefore we ask people to think twice whether the security
+incident report should go to:
+
+ a) The OP-TEE project? Is it an issue in the generic code?
+ b) The chipmaker? Does it only affect a certain platform? Is it a configuration described only under NDA?
+ c) The ones making the end product? Is the issue only present on a certain device?
+
+The OP-TEE team are in some cases are working directly with chipmakers. But it's
+not uncommon that products are made using OP-TEE that the OP-TEE project is
+unaware of. In those cases we would recommend sending the security issue report
+to the company making the end product and that they in turn and if needed reach
+out to the OP-TEE project and/or the chipmaker.
+
 .. _core_team:
 
 Core Team