1 // Copyright 2020 Google LLC 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 15 #ifndef DICE_DICE_H_ 16 #define DICE_DICE_H_ 17 18 #include <stddef.h> 19 #include <stdint.h> 20 21 #include "dice/types.h" 22 23 #ifdef __cplusplus 24 extern "C" { 25 #endif 26 27 #define DICE_CDI_SIZE 32 28 #define DICE_HASH_SIZE 64 29 #define DICE_HIDDEN_SIZE 64 30 #define DICE_INLINE_CONFIG_SIZE 64 31 #define DICE_PRIVATE_KEY_SEED_SIZE 32 32 #define DICE_ID_SIZE 20 33 34 // Contains a full set of input values describing the target program or system. 35 // See the Open Profile for DICE specification for a detailed explanation of 36 // these inputs. 37 // 38 // Fields: 39 // code_hash: A hash or similar representation of the target code. 40 // code_descriptor: An optional descriptor to be included in the certificate. 41 // This descriptor is opaque to the DICE flow and is included verbatim 42 // in the certificate with no validation. May be null. 43 // code_descriptor_size: The size in bytes of |code_descriptor|. 44 // config_type: Indicates how to interpret the remaining config-related 45 // fields. If the type is 'inline', then the 64 byte configuration input 46 // value must be provided in |config_value| and |config_descriptor| is 47 // ignored. If the type is 'descriptor', then |config_descriptor| is 48 // hashed to get the configuration input value and |config_value| is 49 // ignored. 50 // config_value: A 64-byte configuration input value when |config_type| is 51 // kDiceConfigTypeInline. Otherwise, this field is ignored. 52 // config_descriptor: A descriptor to be hashed for the configuration input 53 // value when |config_type| is kDiceConfigTypeDescriptor. Otherwise, 54 // this field is ignored and may be null. 55 // config_descriptor_size: The size in bytes of |config_descriptor|. 56 // authority_hash: A hash or similar representation of the authority used to 57 // verify the target code. If the code is not verified or the authority 58 // is implicit, for example hard coded as part of the code currently 59 // executing, then this value should be set to all zero bytes. 60 // authority_descriptor: An optional descriptor to be included in the 61 // certificate. This descriptor is opaque to the DICE flow and is 62 // included verbatim in the certificate with no validation. May be null. 63 // authority_descriptor_size: The size in bytes of |authority_descriptor|. 64 // mode: The current operating mode. 65 // hidden: Additional input which will not appear in certificates. If this is 66 // not used it should be set to all zero bytes. 67 typedef struct DiceInputValues_ { 68 uint8_t code_hash[DICE_HASH_SIZE]; 69 const uint8_t* code_descriptor; 70 size_t code_descriptor_size; 71 DiceConfigType config_type; 72 uint8_t config_value[DICE_INLINE_CONFIG_SIZE]; 73 const uint8_t* config_descriptor; 74 size_t config_descriptor_size; 75 uint8_t authority_hash[DICE_HASH_SIZE]; 76 const uint8_t* authority_descriptor; 77 size_t authority_descriptor_size; 78 DiceMode mode; 79 uint8_t hidden[DICE_HIDDEN_SIZE]; 80 } DiceInputValues; 81 82 // Derives a |cdi_private_key_seed| from a |cdi_attest| value. On success 83 // populates |cdi_private_key_seed| and returns kDiceResultOk. 84 DiceResult DiceDeriveCdiPrivateKeySeed( 85 void* context, const uint8_t cdi_attest[DICE_CDI_SIZE], 86 uint8_t cdi_private_key_seed[DICE_PRIVATE_KEY_SEED_SIZE]); 87 88 // Derives an |id| from a |cdi_public_key| value. Because public keys can vary 89 // in length depending on the algorithm, the |cdi_public_key_size| in bytes must 90 // be provided. When interpreted as an integer, |id| is big-endian. On success 91 // populates |id| and returns kDiceResultOk. 92 DiceResult DiceDeriveCdiCertificateId(void* context, 93 const uint8_t* cdi_public_key, 94 size_t cdi_public_key_size, 95 uint8_t id[DICE_ID_SIZE]); 96 97 // Executes the main DICE flow. 98 // 99 // Given a full set of input values and the current CDI values, computes the 100 // next CDI values and a matching certificate. See the Open Profile for DICE 101 // specification for a detailed explanation of this flow. 102 // In certain cases, the caller may not need to generate the CDI certificate. 103 // The caller should signal this by setting the certificate parameters to 104 // null/zero values appropriately. 105 // 106 // Parameters: 107 // context: Context provided by the caller that is opaque to this library 108 // but is passed through to the integration-provided operations in 109 // dice/ops.h. The value is, therefore, integration-specific and may be 110 // null. 111 // current_cdi_attest, current_cdi_seal: The current CDI values as produced 112 // by a previous DICE flow. If this is the first DICE flow in a system, 113 // the Unique Device Secret (UDS) should be used for both of these 114 // arguments. 115 // input_values: A set of input values describing the target program or 116 // system. 117 // next_cdi_certificate_buffer_size: The size in bytes of the buffer pointed 118 // to by the |next_cdi_certificate| argument. This should be set to zero 119 // if next CDI certificate should not be computed. 120 // next_cdi_certificate: On success, will be populated with the generated 121 // certificate, up to |next_cdi_certificate_buffer_size| in size. If the 122 // certificate cannot fit in the buffer, |next_cdi_certificate_size| is 123 // populated with the required size and kDiceResultBufferTooSmall is 124 // returned. This should be set to NULL if next CDI certificate should 125 // not be computed. 126 // next_cdi_certificate_actual_size: On success, will be populated with the 127 // size, in bytes, of the certificate data written to 128 // |next_cdi_certificate|. If kDiceResultBufferTooSmall is returned, will 129 // be populated with the required buffer size. This should be set to NULL 130 // if next CDI certificate should not be computed. 131 // next_cdi_attest: On success, will be populated with the next CDI value for 132 // attestation. 133 // next_cdi_seal: On success, will be populated with the next CDI value for 134 // sealing. 135 DiceResult DiceMainFlow(void* context, 136 const uint8_t current_cdi_attest[DICE_CDI_SIZE], 137 const uint8_t current_cdi_seal[DICE_CDI_SIZE], 138 const DiceInputValues* input_values, 139 size_t next_cdi_certificate_buffer_size, 140 uint8_t* next_cdi_certificate, 141 size_t* next_cdi_certificate_actual_size, 142 uint8_t next_cdi_attest[DICE_CDI_SIZE], 143 uint8_t next_cdi_seal[DICE_CDI_SIZE]); 144 145 #ifdef __cplusplus 146 } // extern "C" 147 #endif 148 149 #endif // DICE_DICE_H_ 150