Software APIs
dice.h
1 // Copyright lowRISC contributors (OpenTitan project).
2 // Licensed under the Apache License, Version 2.0, see LICENSE for details.
3 // SPDX-License-Identifier: Apache-2.0
4 
5 #ifndef OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_CERT_DICE_H_
6 #define OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_CERT_DICE_H_
7 
8 #include <stdint.h>
9 
10 #include "sw/device/silicon_creator/lib/attestation.h"
11 #include "sw/device/silicon_creator/lib/cert/cert.h"
12 #include "sw/device/silicon_creator/lib/drivers/hmac.h"
13 #include "sw/device/silicon_creator/lib/drivers/keymgr.h"
14 #include "sw/device/silicon_creator/lib/error.h"
15 #include "sw/device/silicon_creator/lib/ownership/datatypes.h"
16 #include "sw/device/silicon_creator/lib/sigverify/ecdsa_p256_key.h"
17 #include "sw/device/silicon_creator/manuf/base/perso_tlv_data.h"
18 
19 enum {
20  /**
21  * DICE attestation measurement sizes, comprised of a SHA256 digest.
22  */
23  kDiceMeasurementSizeInBits = 256,
24  kDiceMeasurementSizeInBytes = kDiceMeasurementSizeInBits / 8,
25 };
26 
27 extern const dice_cert_format_t kDiceCertFormat;
28 /**
29  * DICE ECC key descriptors.
30  */
31 extern const sc_keymgr_ecc_key_t kDiceKeyUds;
32 extern const sc_keymgr_ecc_key_t kDiceKeyCdi0;
33 extern const sc_keymgr_ecc_key_t kDiceKeyCdi1;
34 
35 /**
36  * Generates the UDS attestation keypair and (unendorsed) X.509 TBS certificate.
37  *
38  * @param otp_creator_sw_cfg_measurement Pointer to the CreatorSwCfg
39  * measurement.
40  * @param otp_owner_sw_cfg_measurement Pointer to the OwnerSwCfg measurement.
41  * @param otp_rot_creator_auth_codesign_measurement Pointer to the
42  * RotCreatorAuthCodesign measurement.
43  * @param otp_rot_creator_auth_state_measurement Pointer to the
44  * RotCreatorAuthState measurement.
45  * @param key_ids Pointer to the (current and endorsement) public key IDs.
46  * @param uds_pubkey Pointer to the (current stage) public key in big endian.
47  * @param[out] cert Buffer to hold the generated UDS certificate.
48  * @param[in,out] cert_size Size of the UDS certificate (input value is the size
49  * of the allocated cert_buf, output value final
50  * computed size of the certificate).
51  * @return The result of the operation.
52  */
53 OT_WARN_UNUSED_RESULT
54 rom_error_t dice_uds_tbs_cert_build(
55  hmac_digest_t *otp_creator_sw_cfg_measurement,
56  hmac_digest_t *otp_owner_sw_cfg_measurement,
57  hmac_digest_t *otp_rot_creator_auth_codesign_measurement,
58  hmac_digest_t *otp_rot_creator_auth_state_measurement,
59  cert_key_id_pair_t *key_ids, ecdsa_p256_public_key_t *uds_pubkey,
60  uint8_t *tbs_cert, size_t *tbs_cert_size);
61 
62 /**
63  * Generates the CDI_0 attestation keypair and X.509 certificate.
64  *
65  * @param rom_ext_measurement Pointer to the ROM_EXT measurement.
66  * @param rom_ext_security_version ROM_EXT security version.
67  * @param key_ids Pointer to the (current and endorsement) public key IDs.
68  * @param cdi_0_pubkey Pointer to the (current stage) public key in big endian.
69  * @param[out] cert Buffer to hold the generated CDI_0 certificate.
70  * @param[in,out] cert_size Size of the CDI_0 certificate (input value is the
71  * size of the allocated cert_buf, output value final
72  * computed size of the certificate).
73  * @return The result of the operation.
74  */
75 OT_WARN_UNUSED_RESULT
76 rom_error_t dice_cdi_0_cert_build(hmac_digest_t *rom_ext_measurement,
77  uint32_t rom_ext_security_version,
78  cert_key_id_pair_t *key_ids,
79  ecdsa_p256_public_key_t *cdi_0_pubkey,
80  uint8_t *cert, size_t *cert_size);
81 
82 /**
83  * Generates the CDI_1 attestation keypair and X.509 certificate.
84  *
85  * @param owner_measurement Pointer to the owner firmware measurement.
86  * @param owner_manifest_measurement Pointer to the owner manifest measurement.
87  * @param owner_security_version Owner firmware security version.
88  * @param key_domain Domain of the Owner SW signing key.
89  * @param key_ids Pointer to the (current and endorsement) public key IDs.
90  * @param cdi_1_pubkey Pointer to the (current stage) public key in big endian.
91  * @param[out] cert Buffer to hold the generated CDI_1 certificate.
92  * @param[in,out] cert_size Size of the CDI_1 certificate (input value is the
93  * size of the allocated cert_buf, output value final
94  * computed size of the certificate).
95  * @return The result of the operation.
96  */
97 OT_WARN_UNUSED_RESULT
98 rom_error_t dice_cdi_1_cert_build(hmac_digest_t *owner_measurement,
99  hmac_digest_t *owner_manifest_measurement,
100  uint32_t owner_security_version,
101  owner_app_domain_t key_domain,
102  cert_key_id_pair_t *key_ids,
103  ecdsa_p256_public_key_t *cdi_1_pubkey,
104  uint8_t *cert, size_t *cert_size);
105 
106 /**
107  * Check if a subject pubkey ID (serial number) or subject pubkey match the
108  * contents of the provided certificate.
109  *
110  * @param cert_obj Pointer to the TLV cert object from the flash.
111  * @param pubkey_id Pointer to the subject pubkey ID (serial number).
112  * @param pubkey Pointer to the subject pubkey contents.
113  * @param[out] cert_valid_output If unmatched, set `cert_valid_output` to
114  * kHardenedBoolFalse for triggering cert regeneration.
115  * @return errors encountered during the check.
116  */
117 OT_WARN_UNUSED_RESULT
118 rom_error_t dice_cert_check_valid(const perso_tlv_cert_obj_t *cert_obj,
119  const hmac_digest_t *pubkey_id,
120  const ecdsa_p256_public_key_t *pubkey,
121  hardened_bool_t *cert_valid_output);
122 
123 #endif // OPENTITAN_SW_DEVICE_SILICON_CREATOR_LIB_CERT_DICE_H_
Return to OpenTitan Documentation