1 /* 2 * Copyright (c) 2022, Arm Limited. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 * 6 */ 7 8 /* This file describes the Delegated Attestation API */ 9 10 #ifndef DELEGATED_ATTESTATION_H 11 #define DELEGATED_ATTESTATION_H 12 13 #include <stddef.h> 14 #include <stdint.h> 15 16 #include "psa/error.h" 17 18 /* RSS Delegated Attestation message types that distinguish its services. */ 19 #define RSS_DELEGATED_ATTEST_GET_DELEGATED_KEY 1001U 20 #define RSS_DELEGATED_ATTEST_GET_PLATFORM_TOKEN 1002U 21 22 /** 23 * The aim of these APIs to get a derived signing key (private only) for the 24 * delegated attestation model and obtain the corresponding platform attestation 25 * token. In the delegated attestation model the final token consist of more 26 * than one subtokens which are signed by different entities. There is a 27 * cryptographical binding between the tokens. The derived delegated attestation 28 * key is bind to the platform token (details below). 29 * 30 * Expected usage model: 31 * - First rss_delegated_attest_get_delegated_key() API need to be called to 32 * obtain the private part of the delegated attestation key. The public part 33 * of key is computed by the cryptographic library when the key is 34 * registered. 35 * - Secondly the rss_delegated_attest_get_token() must be called to obtain 36 * platform attestation token. The hash of the public key (computed by 37 * the hash_algo indicated in the rss_delegated_attest_get_delegated_key() 38 * call) must be the input of this call. This ensures that nothing but the 39 * previously derived delegated key is bindable to the platform token. 40 */ 41 42 /** 43 * Get a delegated attestation key (DAK). 44 * 45 * The aim of the delegated attestation key is to enable other SW components 46 * within the system to sign an attestation token which is different than the 47 * initial/platform token. The initial attestation token MUST contain the hash 48 * of the public delegated key to make a cryptographical binding (hash lock) 49 * between the key and the token. 50 * The initial attestation token has two roles in this scenario: 51 * - Attest the device boot status and security lifecycle. 52 * - Attest the delegated attestation key. 53 * The delegated attestation key is derived from a preprovisioned seed. The 54 * input for the key derivation is the platform boot status. The system can be 55 * attestated with the two tokens together. 56 * 57 * ecc_curve The type of the elliptic curve to which the requested 58 * attestation key belongs. Please check the note section for 59 * limitations. 60 * key_bits The size of the requested attestation key, in bits. 61 * key_buf Pointer to the buffer where the delegated attestation key will 62 * be stored. 63 * key_buf_size Size of allocated buffer for the key, in bytes. 64 * key_size Size of the key that has been returned, in bytes. 65 * hash_algo The hash algorithm that will be used later by the owner of the 66 * requested delegated key for binding it to the platform 67 * attestation token. 68 * 69 * Returns error code as specified in psa_status_t. 70 * 71 * Notes: 72 * - Currently, only the PSA_ECC_FAMILY_SECP_R1 curve type is supported. 73 * - The delegated attestation key must be derived before requesting for the 74 * platform attestation token as they are cryptographically linked together. 75 */ 76 psa_status_t 77 rss_delegated_attest_get_delegated_key(uint8_t ecc_curve, 78 uint32_t key_bits, 79 uint8_t *key_buf, 80 size_t key_buf_size, 81 size_t *key_size, 82 uint32_t hash_algo); 83 84 /** 85 * Get platform attestation token 86 * 87 * dak_pub_hash Pointer to buffer where the hash of the public DAK is 88 * stored. 89 * dak_pub_hash_size Size of the hash value, in bytes. 90 * token_buf Pointer to the buffer where the platform attestation token 91 * will be stored. 92 * token_buf_size Size of allocated buffer for token, in bytes. 93 * token_size Size of the token that has been returned, in bytes. 94 * 95 * Returns error code as specified in psa_status_t. 96 * 97 * A delegated attestation key must be derived before requesting for the 98 * platform attestation token as they are cryptographically linked together. 99 * Otherwise, the token request will fail and the PSA_ERROR_INVALID_ARGUMENT 100 * code will be returned. 101 */ 102 psa_status_t 103 rss_delegated_attest_get_token(const uint8_t *dak_pub_hash, 104 size_t dak_pub_hash_size, 105 uint8_t *token_buf, 106 size_t token_buf_size, 107 size_t *token_size); 108 109 #endif /* DELEGATED_ATTESTATION_H */ 110