1 /*
2  * Copyright (c) 2018-2022, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  */
7 
8 #ifndef __TFM_PLAT_DEVICE_ID_H__
9 #define __TFM_PLAT_DEVICE_ID_H__
10 /**
11  * \file tfm_plat_device_id.h
12  *
13  * The interfaces defined in this file are meant to provide the following
14  * attributes of the device:
15  *  - Instance ID:       Unique identifier of the device.
16  *  - Implementation ID: Original implementation signer of the attestation key.
17  *  - Hardware version:  Identify the GDSII that went to fabrication.
18  */
19 
20 /**
21  * \note The interfaces defined in this file must be implemented for each
22  *       SoC.
23  */
24 
25 #include <stdint.h>
26 #include "tfm_plat_defs.h"
27 
28 #ifdef __cplusplus
29 extern "C" {
30 #endif
31 
32 /**
33  * \def INSTANCE_ID_MAX_SIZE
34  *
35  * \brief Maximum size of instance ID in bytes
36  */
37 #define INSTANCE_ID_MAX_SIZE (33u)
38 
39 /**
40  * \def IMPLEMENTATION_ID_MAX_SIZE
41  *
42  * \brief Maximum size of implementation ID in bytes
43  */
44 #define IMPLEMENTATION_ID_MAX_SIZE (32u)
45 
46 /**
47  * \def CERTIFICATION_REF_MAX_SIZE
48  *
49  * \brief Maximum size of hardware version in bytes
50  *
51  * Recommended to use the European Article Number format: EAN-13 + '-' + 5
52  * https://www.ietf.org/archive/id/draft-tschofenig-rats-psa-token-09.html#name-certification-reference
53  */
54 #define CERTIFICATION_REF_MAX_SIZE (19u)
55 
56 /**
57  * \brief Get the Implementation ID of the device.
58  *
59  * This mandatory claim represents the original implementation signer of the
60  * attestation key and identifies the contract between the report and
61  * verification. A verification service will use this claim to locate the
62  * details of the verification process. The claim will be represented by a
63  * custom EAT claim with a value consisting of a CBOR byte string. The size of
64  * this string will normally be 32 bytes to accommodate a 256 bit hash.
65  *
66  * \param[in/out] size  As an input value it indicates the size of the caller
67  *                      allocated buffer (in bytes) to store the implementation
68  *                      ID. At return its value is updated with the exact size
69  *                      of the implementation ID.
70  * \param[out]    buf   Pointer to the buffer to store the implementation ID
71  *
72  * \return  Returns error code specified in \ref tfm_plat_err_t
73  */
74 enum tfm_plat_err_t tfm_plat_get_implementation_id(uint32_t *size,
75                                                    uint8_t  *buf);
76 
77 /**
78  * \brief Get the PSA certification reference of the device.
79  *
80  * This optional claim provides metadata linking the token to the GDSII that
81  * went to fabrication for this instance. It is represented as CBOR text string.
82  * It is recommended to use for identification the format of the European
83  * Article Number: EAN-13+5.
84  *
85  * \param[in/out] size  As an input value it indicates the size of the caller
86  *                      allocated buffer (in bytes) to store the certification
87  *                      reference. At return its value is updated with the exact
88  *                      size of the certification reference.
89  * \param[out]    buf   Pointer to the buffer to store the certification
90  *                      reference.
91  *
92  * \return  Returns error code specified in \ref tfm_plat_err_t
93  */
94 enum tfm_plat_err_t tfm_plat_get_cert_ref(uint32_t *size, uint8_t *buf);
95 
96 #ifdef __cplusplus
97 }
98 #endif
99 
100 #endif /* __TFM_PLAT_DEVICE_ID_H__ */
101