aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJulian Hall <julian.hall@arm.com>2021-06-21 13:44:33 +0100
committerGyorgy Szing <Gyorgy.Szing@arm.com>2021-07-05 12:47:45 +0200
commitc1cf9120e4ab0b359a27176b079769b9a7e6bb87 (patch)
tree0a70a59f12dc5c55294ff0e23b5abd12ea9c4940
parent7048d3091637689f4849206216b803e0cbf8b89f (diff)
downloadtrusted-services-c1cf9120e4ab0b359a27176b079769b9a7e6bb87.tar.gz
Add attestation service documentation
Adds a page under service descriptions that descibes the attestation service design and related tests. Signed-off-by: Julian Hall <julian.hall@arm.com> Change-Id: I27f12a63862e002f15ab0a065f056024cbe8b45b
-rw-r--r--docs/developer/service-descriptions/attest-service-description.rst269
-rw-r--r--docs/developer/service-descriptions/index.rst1
-rw-r--r--docs/developer/service-descriptions/uml/AttestClaimsModel.puml43
-rw-r--r--docs/developer/service-descriptions/uml/AttestImportedIAKflow.puml21
-rw-r--r--docs/developer/service-descriptions/uml/AttestPartitioning.puml23
-rw-r--r--docs/developer/service-descriptions/uml/AttestSelfGeneratedIAKflow.puml22
6 files changed, 379 insertions, 0 deletions
diff --git a/docs/developer/service-descriptions/attest-service-description.rst b/docs/developer/service-descriptions/attest-service-description.rst
new file mode 100644
index 000000000..2843ede9e
--- /dev/null
+++ b/docs/developer/service-descriptions/attest-service-description.rst
@@ -0,0 +1,269 @@
+Attestation Service Description
+===============================
+Service Overview
+----------------
+The Attestation service is responsible for reporting on the security state of a device.
+Because information is signed, a remote party may verify that the information is intact
+and authentic. The Attestation service can be used as part of an infrastructure for
+remote security monitoring. The Attestation service provider performs the following
+functions:
+
+ 1. Collates information about device hardware and firmware. This information must be obtained in a secure way to provide a suitably trustworthy snapshot of a device's security state.
+ 2. Prepares and signs a report that includes the information as a set of claims about the device.
+
+Like other trusted services, the Attestation service provider runs within a secure
+processing environment such as a secure partition or secondary MCU. Service operations
+are invoked by clients using a service access protocol that defines the serialization of
+requests and responses carried by the underlying RPC layer. Client-side adapters are
+available that support service access using the following C APIs:
+
+ - **PSA Initial Attestation API** - used during normal device operation to obtain a fresh attestation token.
+ - **Attestation Provisioning API** - used during manufacture for key provisioning operations.
+
+Project Directories
+-------------------
+Components within the Trusted Services project related to the Attestation service are
+located under the following directories:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Directory
+ - Contains
+ * - components/service/attestation
+ - Service specific code and API header files.
+ * - protocols/service/attestation
+ - Service access protocol definitions.
+ * - deployments/attestation
+ - Build files and deployment specific code for building the attestation service provider to run in different environments.
+ * - deployments/platform-inspect
+ - A user-space application that retrieves information about platform firmware and hardware and produces a pretty printed output.
+
+Attestation report
+------------------
+A fresh attestation report may be requested at any time to obtain the current view
+of a device's security state. The report is encoded as a CBOR token, signed using
+the CBOR Object Signing and Encryption protocol (COSE). For more information about
+the report contents and encoding, see:
+https://www.psacertified.org/blog/what-is-an-entity-attestation-token/. The following
+text shows the typical content of an attestation report. This report was retrieved
+and decoded using the *platform-inspect* command line application::
+
+ attestation_report:
+ challenge: 32 2d 69 64 ba df b2 f3 28 e8 27 88 50 68 c2 94 7c 4d a9 71 ce 14 e9 f4 88 26 45 9d 2c f5 3c 1b
+ client_id: 0
+ boot_seed: 6c eb 03 90 46 e2 09 27 f2 1c 7c a2 2c 1a a6 a2 bd 41 5e 3c aa be 4a b1 fd 35 52 95 b9 74 32 42
+ security_lifecycle: 3000
+ instance_id: 01 cb e9 65 fc 88 90 69 36 4b b1 0c ef 04 ae 97 aa d7 7c f9 74 41 4d f5 41 0c d3 9d e3 df 97 de c5
+ sw_components:
+ type: BL_2
+ digest: a8 4f b4 7b 54 d9 4b ab 49 73 63 f7 9b fc 66 cb 85 12 ab 18 6f 24 74 01 5d cf 33 f3 80 9e 9b 20
+
+ type: BL_31
+ digest: 2f d3 43 6c 6f ef 9b 11 c2 16 dd 1f 8b df 9b a5 24 14 a5 c1 97 0c 3a 6c 78 bf ef 64 0f c1 23 e1
+
+ type: HW_CONFIG
+ digest: f3 de 4e 17 a1 a5 a7 fe d9 d9 f4 16 3c 49 36 7e ae f7 2f 2a a8 87 e6 b6 22 89 cd 27 dc 1c 80 25
+
+ type: SOC_FW_CONFIG
+ digest: 4e e4 8e 5a e6 50 ed e0 b5 a3 54 8a 1f d6 0e 8a ea 0e 71 75 0e a4 3f 82 76 ce af cd 7c b0 91 e0
+
+ type: BL_32
+ digest: 62 22 4f 0f b0 5d b4 77 1b 3f a5 2e ab 76 1e 61 17 b8 c6 6e ac 8c c8 4d 2e b0 7d 70 08 60 4b 41
+
+ type: BL32_EXTRA1_IMAGE
+ digest: 39 d2 b8 5d 93 5d f6 d8 f8 ed 0c 1a 3a e3 c8 90 72 19 f4 88 5c 79 15 05 7b f0 76 db c1 4c 5d 77
+
+ type: BL_33
+ digest: b5 d6 08 61 dd fa 6d da a3 f7 a5 de d6 8f 6f 39 25 b1 57 fa 3e db 46 42 58 24 8e 81 1c 45 5d 38
+
+ type: NT_FW_CONFIG
+ digest: 25 10 60 5d d4 bc 9d 82 7a 16 9f 8a cc 47 95 a6 fd ca a0 c1 2b c9 99 8f 51 20 ff c6 ed 74 68 5a
+
+Design Description
+------------------
+Components related to the Attestation service are partitioned as follows:
+
+.. uml:: uml/AttestPartitioning.puml
+
+The partitioning into components reflects the following problem areas:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Component
+ - Problem Area
+ * - claims
+ - Collecting diverse information about a device and presenting it in a uniform way. Provides an extensible framework that allows new sources of information to be added while avoiding coupling to other components.
+ * - client
+ - Client side adapters for calling service operations.
+ * - key_mngr
+ - Manages provisioning related operations and access to the key (IAK) used for report signing.
+ * - reporter
+ - Combines the set of claims that forms the content of an attestation report, encoding it and signing using the IAK.
+ * - provider
+ - The service provider that handles incoming requests.
+ * - protocol
+ - The service access protocol definition that describes supported operations and the serialization of input and output parameters.
+
+Claims Model
+''''''''''''
+The set of available claims about a device and the method for obtaining them is likely to
+vary between different platforms. The following are examples of likely variations:
+
+ - The method for collecting boot measurements will depend on the boot loader and on SoC architecture. Some likely variations are:
+
+ - Passed forward using a TPM event log or via a proprietary format.
+ - Boot measurements are stored in TPM PCR type registers that need to be read to obtain claims about loaded components.
+ - The set of information passed forward by the boot loader may vary between platforms. Information such as the boot seed or device lifecycle state may be owned by the boot loader on some platforms but not on others.
+ - Platform vendors may wish to include custom claims within the attestation report that reflect vendor specific views of security state.
+
+To accommodate these variations, a flexible claims model is implemented with the following
+characteristics:
+
+ - Any claim is represented by a common structure with members to identify:
+
+ - The category of claim - e.g. this is a claim about device hardware, firmware, the verification service.
+ - The subject of the claim - a claim specific identifier
+ - A variant id to identify the data type for a claim - e.g. integer, byte string, text string or a collection.
+ - Arbitrarily complex claim structures may be presented in a normalized way using combinations of claim variants.
+ - Claims are collected by a set of 'claim sources'. Each concrete claim source implements the platform specific method for collecting information and representing it in standard way. The set of claim sources used may vary for different deployments.
+ - Claim sources are registered with the claims_register. This is a singleton that provides methods for querying for different sets of claims e.g. all device claims or all firmware measurements. By collating claims by category, tight coupling between the reporter and the set of available claims is avoided.
+
+The following class diagram illustrates the implemented claims model:
+
+.. uml:: uml/AttestClaimsModel.puml
+
+Claim Sources
+"""""""""""""
+It is envisaged that the number of concrete claim sources will grow to cope with differences
+between platforms and the need to include custom claims in attestation reports. The following
+table lists some existing claim sources:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Claim Source
+ - Description
+ * - event_log
+ - A claim source that sources a claim_collection variant. An iterator may be created that allows claims within a TCG event log to be iterated over and accessed.
+ * - boot_seed_generator
+ - Where a boot seed is not available from another source, a boot_seed_generator may be used in a deployment. On the first call to get_claim(), a random boot seed is generated and returned as a byte_string claim variant. On subsequent calls, the same boot seed value is return.
+ * - instance_id
+ - A claim source that returns a device instance ID, derived from the IAK public key.
+ * - null_lifecycle
+ - Used when there is no hardware backed support for the device lifecycle state variable. This claim source just returns a lifecycle state of 'unknown'.
+
+Reporter
+""""""""
+The contents of the attestation report created by the reporter is determined by the set of
+claim sources registered with the claims_register. To generate a PSA compliant attestation
+report, the reporter queries for the following categories of claim:
+
+ - Device
+ - Verification service
+ - Boot measurements
+
+Having collated all claims, the report is serialized as a CBOR object using the qcbor
+open source library. The CBOR object is then signed using the *t_cose* library to produce
+the final attestation token.
+
+Provisioning Flows
+------------------
+The Attestation service uses the IAK (an ECDSA key pair) for signing attestation reports.
+An external verification service needs a way of establishing trust in the IAK used by a
+device to sign a report. This trust relationship is formed when a device is provisioned
+during manufacture. During provisioning, the following steps must be performed in a
+secure manufacturing environment:
+
+ 1. A unique IAK is generated and stored as a persistent key in the device's secure key store.
+ 2. The IAK public key is obtained and stored in a central database of trusted devices. The hash of the IAK public key (the device's instance ID) is used as the database key for accessing the stored key.
+
+To verify the authenticity of an attestation report, an external verifier must query
+the database using the instance ID claim contained within the report. The signature on
+the report is viewed as authentic if the following are true:
+
+ - A key record exists for the given instance ID within the database.
+ - The signature is verified successfully using the corresponding public key.
+
+The attestation access protocol supports operations to support provisioning. These
+operations may be invoked using simple client C API (see *attest_provision.h*) or by
+using the access protocol directly for non-C clients. The following two alternative
+provisioning flows are supported:
+
+Self-generated IAK
+''''''''''''''''''
+When a device powers up before provisioning has been performed, no IAK will exist in
+the device's key store. As long as no attestation related service operations are
+performed, the device will remain in this state. To trigger the self generation of
+an IAK, factory provisioning software should call the *export_iak_public_key* operation.
+If no IAK exists, one will be generated using the device's TRNG. A benefit of this
+flow is that the IAK private key value is never externally exposed. To support test
+deployments where no persistent storage is used, the self-generated IAK flow may
+optionally generate a volatile key instead of persistent key.:
+
+.. uml:: uml/AttestSelfGeneratedIAKflow.puml
+
+Imported IAK
+''''''''''''
+To support external generation of the IAK, a one-time key import operation is also
+supported. When a device is in the pre-provisioned state where no IAK exists, the
+import_iak may be called by factory provisioning software. Importantly, *import_iak*
+may only be called once. An attempt to call it again will be rejected.:
+
+.. uml:: uml/AttestImportedIAKflow.puml
+
+Testing the Attestation Service
+-------------------------------
+The following CppUtest based test suites are available for attestation service testing.
+All component and service level tests may be run on a real target device and as part
+of a native PC built binary.
+
+Component-Level Test Suites
+'''''''''''''''''''''''''''
+Test suites included in deployments of *component-test*:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Test Suite
+ - Coverage
+ - File Location
+ * - TcgEventLogTests
+ - Tests decoding and iterator access to a TCG event log.
+ - service/attestation/claims/sources/event_log/test
+ * - AttestationReporterTests
+ - Checks the contents and signing of a generated attestation report.
+ - service/attestation/test/component
+
+Service-Level Test Suites
+'''''''''''''''''''''''''
+Test suites included in deployments of *ts-service-test*. Test cases act as conventional
+service clients:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Test Suite
+ - Coverage
+ - File Location
+ * - AttestationServiceTests
+ - Different attestation token request scenarios
+ - service/attestation/test/service
+ * - AttestationProvisioningTests
+ - Tests provisioning flows and checks defence against misuse of provisioning operations.
+ - service/attestation/test/service
+
+Environment Tests
+'''''''''''''''''
+When deployed within a secure partition, the attestation SP relies on access to externally
+provided information such as the TPM event log. Test have been added to the *env_test* SP
+deployment to check that features that the attestation SP relies on are working as expected.
+Tests included in the *env_test* SP deployment may be invoked from Linux user-space using the
+*ts-remote-test/arm-linux* deployment.
+
+--------------
+
+*Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.*
+
+SPDX-License-Identifier: BSD-3-Clause
diff --git a/docs/developer/service-descriptions/index.rst b/docs/developer/service-descriptions/index.rst
index 6762238cb..5962e3709 100644
--- a/docs/developer/service-descriptions/index.rst
+++ b/docs/developer/service-descriptions/index.rst
@@ -5,6 +5,7 @@ Service Descriptions
:maxdepth: 1
:caption: Contents:
+ attest-service-description
crypto-service-description
secure-storage-service-description
diff --git a/docs/developer/service-descriptions/uml/AttestClaimsModel.puml b/docs/developer/service-descriptions/uml/AttestClaimsModel.puml
new file mode 100644
index 000000000..fb54f71ef
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/AttestClaimsModel.puml
@@ -0,0 +1,43 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+abstract class claim_iterator {
+ {abstract} void first()
+ {abstract} void next()
+ {abstract} bool is_done()
+ {abstract} claim current()
+}
+
+abstract class claim_source {
+ {abstract} bool get_claim(claim *claim)
+}
+
+class claim {
+ +category: int
+ +subject_id: int
+ +variant_id: int
+}
+
+class claims_register <<singleton>> {
+ void add_claim_source(claim_source)
+ void query_by_category(category, claim_vector)
+}
+
+claim <|-- claim_collection
+claim <|-- text_string_claim
+claim <|-- byte_string_claim
+claim <|-- integer_claim
+claim <|-- measurement_claim
+
+claim_iterator ..> claim
+claim_collection ..> claim_iterator
+claim_source ..> claim
+claims_register -> "0..*" claim_source
+
+@enduml
diff --git a/docs/developer/service-descriptions/uml/AttestImportedIAKflow.puml b/docs/developer/service-descriptions/uml/AttestImportedIAKflow.puml
new file mode 100644
index 000000000..fef117c05
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/AttestImportedIAKflow.puml
@@ -0,0 +1,21 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+participant "factory app"
+participant "attestation service"
+participant "keystore"
+
+hnote over "keystore": empty
+"factory app" -> "attestation service" : import_iak
+"attestation service" -> "keystore" : check_exists
+"attestation service" <-- "keystore" : false
+"attestation service" -> "keystore" : store_key
+hnote over "keystore": provisioned
+"factory app" <-- "attestation service" : success
+
+@enduml
diff --git a/docs/developer/service-descriptions/uml/AttestPartitioning.puml b/docs/developer/service-descriptions/uml/AttestPartitioning.puml
new file mode 100644
index 000000000..9e8586292
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/AttestPartitioning.puml
@@ -0,0 +1,23 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+
+package claims
+package client
+package key_mngr
+package reporter
+package provider
+package protocol
+
+client ..> protocol
+provider ..> protocol
+provider ..> reporter
+provider ..> key_mngr
+reporter ..> claims
+
+@enduml
diff --git a/docs/developer/service-descriptions/uml/AttestSelfGeneratedIAKflow.puml b/docs/developer/service-descriptions/uml/AttestSelfGeneratedIAKflow.puml
new file mode 100644
index 000000000..7fdae1b9a
--- /dev/null
+++ b/docs/developer/service-descriptions/uml/AttestSelfGeneratedIAKflow.puml
@@ -0,0 +1,22 @@
+'-------------------------------------------------------------------------------
+' Copyright (c) 2021, Arm Limited and Contributors. All rights reserved.
+'
+' SPDX-License-Identifier: BSD-3-Clause
+'
+'-------------------------------------------------------------------------------
+
+@startuml
+participant "factory app"
+participant "attestation service"
+participant "keystore"
+
+hnote over "keystore": empty
+"factory app" -> "attestation service" : export_iak_public_key
+"attestation service" -> "keystore" : check_exists
+"attestation service" <-- "keystore" : false
+"attestation service" -> "attestation service" : generate_key
+"attestation service" -> "keystore" : store_key
+hnote over "keystore": provisioned
+"factory app" <-- "attestation service" : public_key
+
+@enduml