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 #include <dice/ops/clear_memory.h> 21 22 // These are the set of functions that implement various operations that the 23 // main DICE functions depend on. They are provided as part of an integration 24 // and resolved at link time. 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 // Retrieves the DICE key parameters based on the key pair generation 31 // algorithm set up at compile time or in the |context| parameter at runtime. 32 DiceResult DiceGetKeyParam(void* context, DicePrincipal principal, 33 DiceKeyParam* key_param); 34 35 // An implementation of SHA-512, or an alternative hash. Hashes |input_size| 36 // bytes of |input| and populates |output| on success. 37 DiceResult DiceHash(void* context, const uint8_t* input, size_t input_size, 38 uint8_t output[DICE_HASH_SIZE]); 39 40 // An implementation of HKDF-SHA512, or an alternative KDF. Derives |length| 41 // bytes from |ikm|, |salt|, and |info| and populates |output| on success. 42 // |Output| must point to a buffer of at least |length| bytes. 43 DiceResult DiceKdf(void* context, size_t length, const uint8_t* ikm, 44 size_t ikm_size, const uint8_t* salt, size_t salt_size, 45 const uint8_t* info, size_t info_size, uint8_t* output); 46 47 // Deterministically generates a public and private key pair from |seed|. 48 // Since this is deterministic, |seed| is as sensitive as a private key and can 49 // be used directly as the private key. The |private_key| may use an 50 // implementation defined format so may only be passed to the |sign| operation. 51 DiceResult DiceKeypairFromSeed( 52 void* context, DicePrincipal principal, 53 const uint8_t seed[DICE_PRIVATE_KEY_SEED_SIZE], 54 uint8_t public_key[DICE_PUBLIC_KEY_BUFFER_SIZE], 55 uint8_t private_key[DICE_PRIVATE_KEY_BUFFER_SIZE]); 56 57 // Calculates a signature of |message_size| bytes from |message| using 58 // |private_key|. |private_key| was generated by |keypair_from_seed| to allow 59 // an implementation to use their own private key format. |signature| points to 60 // the buffer where the calculated signature is written. 61 DiceResult DiceSign(void* context, const uint8_t* message, size_t message_size, 62 const uint8_t private_key[DICE_PRIVATE_KEY_BUFFER_SIZE], 63 uint8_t signature[DICE_SIGNATURE_BUFFER_SIZE]); 64 65 // Verifies, using |public_key|, that |signature| covers |message_size| bytes 66 // from |message|. 67 DiceResult DiceVerify(void* context, const uint8_t* message, 68 size_t message_size, 69 const uint8_t signature[DICE_SIGNATURE_BUFFER_SIZE], 70 const uint8_t public_key[DICE_PUBLIC_KEY_BUFFER_SIZE]); 71 72 // Generates an X.509 certificate, or an alternative certificate format, from 73 // the given |subject_private_key_seed| and |input_values|, and signed by 74 // |authority_private_key_seed|. The subject private key seed is supplied here 75 // so the implementation can choose between asymmetric mechanisms, for example 76 // ECDSA vs Ed25519. 77 DiceResult DiceGenerateCertificate( 78 void* context, 79 const uint8_t subject_private_key_seed[DICE_PRIVATE_KEY_SEED_SIZE], 80 const uint8_t authority_private_key_seed[DICE_PRIVATE_KEY_SEED_SIZE], 81 const DiceInputValues* input_values, size_t certificate_buffer_size, 82 uint8_t* certificate, size_t* certificate_actual_size); 83 84 #ifdef __cplusplus 85 } // extern "C" 86 #endif 87 88 #endif // DICE_OPS_H_ 89