diff options
author | Gyorgy Szing <Gyorgy.Szing@arm.com> | 2019-04-17 21:08:48 +0200 |
---|---|---|
committer | Gyorgy Szing <Gyorgy.Szing@arm.com> | 2019-05-03 09:08:51 +0200 |
commit | db9783ceb84ae0c99205bc0a8bb3214b2c3a2089 (patch) | |
tree | 2b1025a8b6436d196af7e06416a6edf66014a8a7 /docs/user_guides/services/tfm_attestation_integration_guide.md | |
parent | 74dae3cf92b7c4a52ff629c353649f43fcfa5c86 (diff) | |
download | trusted-firmware-m-db9783ceb84ae0c99205bc0a8bb3214b2c3a2089.tar.gz |
Doc: convert markdown files to rst
The official documentation format for TF-M is becoming Restructured
Text. This change converts the existing .md files to the new format.
Due to support for documentation of external code (/lib) md support is
kept.
Change-Id: I3c1aef5d22442e0c7c362a40a8d344a266dc0940
Signed-off-by: Gyorgy Szing <Gyorgy.Szing@arm.com>
Diffstat (limited to 'docs/user_guides/services/tfm_attestation_integration_guide.md')
-rw-r--r-- | docs/user_guides/services/tfm_attestation_integration_guide.md | 396 |
1 files changed, 0 insertions, 396 deletions
diff --git a/docs/user_guides/services/tfm_attestation_integration_guide.md b/docs/user_guides/services/tfm_attestation_integration_guide.md deleted file mode 100644 index d6085f4665..0000000000 --- a/docs/user_guides/services/tfm_attestation_integration_guide.md +++ /dev/null @@ -1,396 +0,0 @@ -# TF-M Initial Attestation Service Integration Guide - -## Introduction -TF-M Initial Attestation Service allows the application to prove the device -identity during an authentication process to a verification entity. The initial -attestation service can create a token on request, which contains a fix set of -device specific data. Device must contain an attestation key pair, which is -unique per device. The token is signed with the private part of attestation key -pair. The public part of the key pair is known by the verification entity. The -public key is used to verify the token authenticity. The data items in the token -used to verify the device integrity and assess its trustworthiness. Attestation -key provisioning is out of scope for the attestation service and is expected to -take part during manufacturing of the device. - -## Current service limitations -- **Signing of token** - In the current implementation the token is not properly -signed. Signature is generated according to the -[COSE](https://datatracker.ietf.org/doc/rfc8152/) format. But its actual value -is not a correct ECDSA P256 signature, due to the lack of support of the ECDSA -algorithm in the current implementation of the TF-M Crypto service. A fake -signature is created, which is the concatenation of the token's hash value -twice. - -## Claims in the initial attestation token -The initial attestation token is formed of claims. A claim is a data item, -which is represented in a key - value structure. The following fixed set of -claims are included in the token: -- **Challenge**: Input object from caller. Can be a single nonce from server or -hash of nonce and attested data. It is intended to provide freshness to reports -and the caller has responsibility to arrange this. Allowed length: 32, 48, -64 bytes. The claim is modeled to be eventually represented by the EAT standard -claim nonce. Until such a time as that standard exists, the claim will be -represented by a custom claim. Value is encoded as byte string. - -- **Instance ID**: It represents the unique identifier of the instance. In the -PSA definition it is a hash of the public attestation key of the instance. The -claim is modeled to be eventually represented by the EAT standard claim UEID of -type GUID. Until such a time as that standard exists, the claim will be -represented by a custom claim Value is encoded as byte string. - -- **Verification service indicator**: Optional, recommended claim. It is used by -a Relying Party to locate a validation service for the token. The value is a -text string that can be used to locate the service or a URL specifying the -address of the service. The claim is modeled to be eventually represented by -the EAT standard claim origination. Until such a time as that standard exists, -the claim will be represented by a custom claim. Value is encoded as text -string. - -- **Profile definition**: Optional, recommended claim. It contains the name of a -document that describes the 'profile' of the token, being a full description of -the claims, their usage, verification and token signing. The document name may -include versioning. Custom claim with a value encoded as text string. - -- **Implementation ID**: It represents the original implementation signer of the -attestation key and identifies the contract between the report and verification. -A verification service will use this claim to locate the details of the -verification process. Custom claim with a value encoded as byte string. - -- **Security lifecycle**: It represents the current lifecycle state of the -instance. Custom claim with a value encoded as an integer. - -- **Client ID**: The partition ID of that secure partition or non-secure thread -who called the initial attestation API. Custom claim with a value encoded as a -`signed` integer. Negative number represents non-secure caller, positive numbers -represents secure callers, zero is invalid. - -- **HW version**: Optional claim. Globally unique number in EAN-13 format -identifying the GDSII that went to fabrication, HW and ROM. It can be used to -reference the security level of the PSA-ROT via a certification website. Custom -claim with a value is encoded as text string. - -- **Boot seed**: It represents a random value created at system boot time that -will allow differentiation of reports from different system sessions. The size -is 32 bytes. Custom claim with a value is encoded as byte string. - -- **Software components**: Optional, recommended claim. It represents the -software state of the system. The value of the claim is an array of CBOR map -entries, with one entry per software component within the device. Each map -contains multiple claims that describe evidence about the details of the -software component. - - - **Measurement type**: Optional claim. It represents the role of the software - component. Value is encoded as short(!) text string. - - - **Measurement value**: It represents a hash of the invariant software - component in memory at start-up time. The value must be a cryptographic hash - of 256 bits or stronger. Value is encoded as byte string. - - - **Security epoch**: Optional claim. It represents the security control point - of the software component. Value is encoded as unsigned integer. - - - **Version**: Optional claim. It represents the issued software version. Value - is encoded as text string. - - - **Signer ID**: It represents the hash of a signing authority public key. - Value is encoded as byte string. - - - **Measurement description**: Optional claim. It represents the way in which - the measurement value of the software component is computed. Value is encoded - as text string containing an abbreviated description (name) of the measurement - method. - -- **No software measurements**: In the event that the implementation does not -contain any software measurements then the software components claim above can -be omitted but instead it is mandatory to include this claim to indicate this is -a deliberate state. Custom claim a value is encoded as an unsigned integer set -to 1. - -## Initial attestation token (IAT) data encoding -The initial attestation token is planned to be aligned with future version of -[Entity Attestation Token](https://tools.ietf.org/html/draft-mandyam-eat-01) -format. The token is encoded according to the -[CBOR](https://tools.ietf.org/html/rfc7049) format and signed according to -[COSE](https://tools.ietf.org/html/rfc8152) standard. - -## Code structure -The PSA interface for the Initial Attestation Service is located in -`interface/include`. -The only header to be included by applications that want to use functions from -the PSA API is `psa_initial_attestation.h`. -The TF-M Initial Attestation Service source files are located in -`secure_fw/services/initial_attestation`. -The CBOR library is located in `lib/ext/qcbor` folder. - -### Service source files -- CBOR library: - - `lib/ext/qcbor`: This library is used to create a proper CBOR token. It can - be used on 32-bit and 64-bit machines. It was designed to suite constrained - devices with low memory usage and without dynamic memory allocation. It is a - fork of this external - [QCBOR library](https://github.com/laurencelundblade/QCBOR). - - `lib/ext/qcbor/inc/qcbor.h`: Public API documentation of CBOR library. -- COSE library: - - `lib/t_cose`: This library is used to sign a CBOR token and create the COSE - header and signature around the initial attestation token. Only a subset of the - [COSE](https://tools.ietf.org/html/rfc8152) standard is implemented. Only the - cose_sign1 signature schema is supported. - - `lib/t_cose/src/t_cose_crypto.h`: Expose an API to bind `t_cose` library with - available crypto library in the device. - - `lib/t_cose/src/t_cose_psa_crypto.c`: Implements the exposed API and ports - `t_cose` to psa_crypto library. -- Initial Attestation Service: - - `attestation_core.c` : Implements core functionalities such as implementation - of APIs, retrieval of claims and token creation. - - `attest_token.c`: Implements the token creation function such as start and - finish token creation and adding claims to the token. - - `attestation_crypto_stub.c`: Temporary file, it implements the missing - psa_crypto APIs. - - `attestation_key.c`: Get the attestation key from platform layer and register - it to psa_crypto service for further usage. - - `tfm_attestation.c`: Implements the SPM abstraction layer, and bind the - attestation service to the SPM implementation in TF-M project. - - `tfm_attestation_secure_api.c`: Implements the secure API layer to allow - other services in the secure domain to request functionalities from the - attestation service using the PSA API interface. - -### Service interface definitions -- **Boot loader interface**: The attestation service might include data in the -token about the distinct software components in the device. This data is -provided by the boot loader and must be encoded in the TLV format, definition -is described below in the boot loader interface paragraph. Possible claims in -the boot status are describe above in the software components paragraph. -- **Hardware abstraction layer**: - - Headers are located in `platform/include` folder. - - `tfm_attest_hal.h`: Expose an API to get the following claims: security - lifecycle, verification service indicator, profile definition. - - `tfm_plat_boot_seed.h`: Expose an API to get the boot seed claim. - - `tfm_plat_device_id.h`: Expose an API to get the following claims: - implementation ID, hardware version, instance ID. -- **SPM interface**: - - `attestation.h`: Expose an API to bind attestation service to an SPM - implementation. -- **PSA interface**: - - `psa_initial_attestation.h`: Public API definition of initial attestation - service. -- **Crypto interface**: - - `t_cose_crypto.h`: Expose an API to bind the `t_cose` implementation to any - cryptographic library. - - `tfm_plat_crypto_keys.h`: Expose an API to get the attestation key from - platform layer. - -### PSA interface -The TF-M Initial Attestation Service exposes the following PSA interface: - ``` c - enum psa_attest_err_t - psa_initial_attest_get_token(const uint8_t *challenge_obj, - uint32_t challenge_size, - uint8_t *token, - uint32_t *token_size); - -enum psa_attest_err_t -psa_initial_attest_get_token_size(uint32_t challenge_size, - uint32_t *token_size); -``` -The caller must allocate a large enough buffer, where the token is going to be -created by Initial Attestation Service. The size of the created token is highly -dependent on the number of software components in the system and the provided -attributes of these. -The `psa_initial_attest_get_token_size()` function can be called to get the -exact size of the created token. - -System integrators might need to port these interfaces to a custom secure -partition manager implementation (SPM). Implementation in TF-M project can be -found here: -- `interface/src/tfm_initial_attestation_api.c`: non-secure interface -implementation -- `secure_fw/services/initial_attestation/tfm_attestation_secure_api.c`: secure -interface implementation - -### Secure Partition Manager (SPM) interface -The Initial Attestation Service defines the following interface towards the -secure partition manager (SPM). System integrators **must** port this -interface according to their SPM implementation. -```c -enum psa_attest_err_t -attest_get_boot_data(uint8_t major_type, void *ptr, uint32_t len); - -enum psa_attest_err_t -attest_get_caller_client_id(int32_t *caller_id); - -enum psa_attest_err_t -attest_check_memory_access(void *addr, - uint32_t size, - enum attest_memory_access access); -``` -- `attest_get_boot_data()`: Service can retrieve the relevant data from shared -memory area between boot loader and runtime software. It might be the case that -only SPM has direct access to the shared memory area, therefore this function -can be used to copy the service related data from shared memory to a local -memory buffer. In TF-M implementation this function must be called during -service initialization phase, because the shared memory region is deliberately -overlapping with secure main stack to spare some memory and reuse this area -during execution. If boot loader is not available in the system to provide -attributes of software components then this function must be implemented in a -way that just initialize service's memory buffer to: - ```c - struct shared_data_tlv_header *tlv_header = - (struct shared_data_tlv_header *)ptr; - tlv_header->tlv_magic = 2016; - tlv_header->tlv_tot_len = sizeof(struct shared_data_tlv_header *tlv_header); - ``` - -- `attest_get_caller_client_id()`: Retrieves the ID of the caller thread. -- `attest_check_memory_access()`: Validates the availability and access rights -of memory regions received as input data: challenge object, token buffer, etc. -- `tfm_client.h`: Service relies on the following external definitions, which -must be present or included in this header file: - - ```c - typedef struct psa_invec { - const void *base; - size_t len; - } psa_invec; - - typedef struct psa_outvec { - void *base; - size_t len; - } psa_outvec; - ``` - -### Hardware abstraction layer: -The following API definitions are intended to retrieve the platform specific -claims. System integrators **must** implement these interface according to their -SoC and software design. Detailed definition of the claims are above in the -claims in the initial attestation token paragraph. -- `tfm_attest_hal_get_security_lifecycle()`: Get the security lifecycle of the -device. -- `tfm_attest_hal_get_verification_service()`: Get the verification service -indicator for initial attestation. -- `tfm_attest_hal_get_profile_definition()`: Get the name of the profile -definition document for initial attestation. -- `tfm_plat_get_boot_seed()`: Get the boot seed, which is a constant random -number during a boot cycle. -- `tfm_plat_get_instance_id()`: Get the UEID of the device. -- `tfm_plat_get_implementation_id`: Get the implementation ID of the device. -- `tfm_plat_get_hw_version`: Get the hardware version of the device. - -### Boot loader interface -It is **recommended** to have a secure boot loader in the boot chain, which is -capable of measuring the runtime firmware components (calculates the hash value -of firmware images) and provide other attributes of these (version, type, etc). - -The shared data between boot loader and runtime software is TLV encoded. The -definition of TLV structure is described in `bl2/include/tfm_boot_status.h`. -The shared data is stored in a well known location in secure internal memory -and this is a contract between boot loader and runtime SW. - -The structure of shared data must be the following: - - At the beginning there must be a header: `struct shared_data_tlv_header` - This contains a magic number and a size field which covers the entire - size of the shared data area including this header. - ```c - struct shared_data_tlv_header { - uint16_t tlv_magic; - uint16_t tlv_tot_len; - }; - ``` - - After the header there come the entries which are composed from an entry - header structure: `struct shared_data_tlv_entry` and the data. In the entry - header is a type field `tlv_type` which identify the consumer of the entry - in the runtime software and specify the subtype of that data item. There is - a size field `tlv_len` which covers the size of the entry header and the - data. After this structure comes the actual data. - ```c - struct shared_data_tlv_entry { - uint16_t tlv_type; - uint16_t tlv_len; - }; - ``` - - Arbitrary number and size of data entry can be in the shared memory area. - -The table below gives of overview about the `tlv_type` field in the entry -header. The `tlv_type` always composed from a major and minor number. Major -number identifies the addressee in runtime software, which the data entry is -sent to. Minor number used to encode more info about the data entry. The actual -definition of minor number could change per major number. In case of boot -status data, which is going to be processed by initial attestation service -the minor number is split further to two part: `sw_module` and `claim`. The -`sw_module` identifies the SW component in the system which the data item -belongs to and the `claim` part identifies the exact type of the data. - -`tlv_type` description: -``` -|------------------------------------------------ | -| tlv_type (16 bits) | -|-------------------------------------------------| -| tlv_major(4 bits) | tlv_minor(12 bits) | -|-------------------------------------------------| -| MAJOR_IAS | sw_module(6 bits) | claim(6 bits) | -|-------------------------------------------------| -| MAJOR_CORE | TBD | -|-------------------------------------------------| -``` - -Overall structure of shared data: -``` ---------------------------------------------------------------- -| Magic number(uint16_t) | Shared data total length(uint16_t) | ---------------------------------------------------------------- -| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | ---------------------------------------------------------------- -| Raw data | ---------------------------------------------------------------- -| . | -| . | -| . | ---------------------------------------------------------------- -| Major_type(4 bits) | Minor_type(12 bits) | Length(uint16_t) | ---------------------------------------------------------------- -| Raw data | ---------------------------------------------------------------- -``` - -### Crypto interface -Device **must** contain an asymmetric key pair. The private part of it is used -to sign the initial attestation token. Current implementation supports only the -ECDSA P256 signature over SHA256. The public part of the key pair is used to -create the key identifier (kid) in the unprotected part of the COSE header. The -kid is used by verification entity to look up the corresponding public key to -verify the signature in the token. The `t_cose` part of the initial attestation -service implements the signature generation and kid creation. But the actual -calculation of token's hash and signature is done by the Crypto service in the -device. System integrators might need to re-implement the following functions -if they want to use initial attestation service with a different cryptographic -library than Crypto service: -- `t_cose_crypto_pub_key_sign()`: Calculates the signature over a hash value. -- `t_cose_crypto_get_ec_pub_key()`: Get the public key to create the key -identifier. -- `t_cose_crypto_hash_start()`: Start a multipart hash operation. -- `t_cose_crypto_hash_update()`: Add a message fragment to a multipart hash -operation. -- `t_cose_crypto_hash_finish()`:Finish the calculation of the hash of a message. - -Interface needed by verification code: -- `t_cose_crypto_pub_key_verify()`: Verify the signature over a hash value. - -#### Key handling -The provisioning of the initial attestation key is out of scope of the service -and this document. It is assumed that device maker provisions the unique -asymmetric key pair during the manufacturing process. The following API is -defined to retrieve the attestation key pair from platform layer. Software -integrators **must** port this interface according to their SoC design and make -sure that key pair is available by Crypto service: -- `tfm_plat_get_initial_attest_key()`: Retrieve the initial attestation key pair -from platform layer. - -In TF-M project the attestation key is retrieved by initial attestation service. -The key is registered and unregistered to the Crypto service by attestation -service with `psa_import_key()` and `psa_destroy_key()` API calls for further -usage. See in `attestation_key.c`. In other implementation if the attestation -key is directly retrieved by the Crypto service then this key handling is not -necessary. - - -------------- - -*Copyright (c) 2018-2019, Arm Limited. All rights reserved.* |