1 // Copyright 2021 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_OPS_H_ 16 #define DICE_OPS_H_ 17 18 #include <dice/config.h> 19 #include <dice/dice.h> 20 21 // These are the set of functions that implement various operations that the 22 // main DICE functions depend on. They are provided as part of an integration 23 // and resolved at link time. 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 // An implementation of SHA-512, or an alternative hash. Hashes |input_size| 30 // bytes of |input| and populates |output| on success. 31 DiceResult DiceHash(void* context, const uint8_t* input, size_t input_size, 32 uint8_t output[DICE_HASH_SIZE]); 33 34 // An implementation of HKDF-SHA512, or an alternative KDF. Derives |length| 35 // bytes from |ikm|, |salt|, and |info| and populates |output| on success. 36 // |Output| must point to a buffer of at least |length| bytes. 37 DiceResult DiceKdf(void* context, size_t length, const uint8_t* ikm, 38 size_t ikm_size, const uint8_t* salt, size_t salt_size, 39 const uint8_t* info, size_t info_size, uint8_t* output); 40 41 // Deterministically generates a public and private key pair from |seed|. 42 // Since this is deterministic, |seed| is as sensitive as a private key and can 43 // be used directly as the private key. The |private_key| may use an 44 // implementation defined format so may only be passed to the |sign| operation. 45 DiceResult DiceKeypairFromSeed(void* context, 46 const uint8_t seed[DICE_PRIVATE_KEY_SEED_SIZE], 47 uint8_t public_key[DICE_PUBLIC_KEY_SIZE], 48 uint8_t private_key[DICE_PRIVATE_KEY_SIZE]); 49 50 // Calculates a signature of |message_size| bytes from |message| using 51 // |private_key|. |private_key| was generated by |keypair_from_seed| to allow 52 // an implementation to use their own private key format. |signature| points to 53 // the buffer where the calculated signature is written. 54 DiceResult DiceSign(void* context, const uint8_t* message, size_t message_size, 55 const uint8_t private_key[DICE_PRIVATE_KEY_SIZE], 56 uint8_t signature[DICE_SIGNATURE_SIZE]); 57 58 // Verifies, using |public_key|, that |signature| covers |message_size| bytes 59 // from |message|. 60 DiceResult DiceVerify(void* context, const uint8_t* message, 61 size_t message_size, 62 const uint8_t signature[DICE_SIGNATURE_SIZE], 63 const uint8_t public_key[DICE_PUBLIC_KEY_SIZE]); 64 65 // Generates an X.509 certificate, or an alternative certificate format, from 66 // the given |subject_private_key_seed| and |input_values|, and signed by 67 // |authority_private_key_seed|. The subject private key seed is supplied here 68 // so the implementation can choose between asymmetric mechanisms, for example 69 // ECDSA vs Ed25519. 70 DiceResult DiceGenerateCertificate( 71 void* context, 72 const uint8_t subject_private_key_seed[DICE_PRIVATE_KEY_SEED_SIZE], 73 const uint8_t authority_private_key_seed[DICE_PRIVATE_KEY_SEED_SIZE], 74 const DiceInputValues* input_values, size_t certificate_buffer_size, 75 uint8_t* certificate, size_t* certificate_actual_size); 76 77 // Securely clears |size| bytes at |address|. This project contains a basic 78 // implementation. OPENSSL_cleanse from boringssl, SecureZeroMemory from 79 // Windows and memset_s from C11 could also be used as an implementation but a 80 // particular target platform or toolchain may have a better implementation 81 // available that can be plugged in here. Care may be needed to ensure sensitive 82 // data does not leak due to features such as caches. 83 void DiceClearMemory(void* context, size_t size, void* address); 84 85 #ifdef __cplusplus 86 } // extern "C" 87 #endif 88 89 #endif // DICE_OPS_H_ 90