Package: keymgr_pkg

Description

Copyright lowRISC contributors.
Licensed under the Apache License, Version 2.0, see LICENSE for details.
SPDX-License-Identifier: Apache-2.0

key manager package

Signals

Name Type Description
keymgr_pkg endpackage

Constants

Name Type Value Description
KeyWidth int 256
CDIs int 2 2 different CDIs, sealing / attestation
CdiWidth int prim_util_pkg::vbits(CDIs)
OtbnKeyWidth int 384
DigestWidth int 128 uses truncated hash
KmacDataIfWidth int 64 KMAC interface data width
KeyMgrStages int 3 Number of key manager stages (creator, ownerInt, owner)
SwBindingWidth int 32 * keymgr_reg_pkg::NumSwBindingReg
SaltWidth int 32 * keymgr_reg_pkg::NumSaltReg
Shares int 2 number of key shares
EdnWidth int edn_pkg::ENDPOINT_BUS_WIDTH
HealthStateWidth int 128 These should be defined in another module's package
DevIdWidth int 256
MaxWidth int 256
seed_t seed_t 256'h3a0a6d73cd50897de4d744bd65ebdb3837ea77087d878651c517c18a5742b2f9
seed_t seed_t 256'h6d234651d535ebb0dce4d82f503096614355fc7b84595e4f67a866177d421df6
seed_t seed_t 256'hdba98db4fb1413b32fd5a4deac3ce546966a4bc2761235643358c8e76083d382
seed_t seed_t 256'h8c0a27ef53e0e0bf5f5f5e26a30a0d0db10761ed802c6d2fd22873209976021e
seed_t seed_t 256'h99cadb2c2d9b438591d943a89bc64dbb3bc2abc842eeea5faf74d27f7a7c99b6
seed_t seed_t 256'hd551b351decbb6f687c7f5c845363f12d6411fae812e16b23bc8ae59885a56b1
seed_t seed_t 256'h6EECBF9FC3C64230421DA1EAEC48F871070A3582E71AD4059D5D550784E9B9DE Target based deriviation seeds These are used during the generation stages for sideload
seed_t seed_t 256'hC1104CD94EBA084FA6438188038006489F3DF38771214AE0BBA65CEB9BC2366F
seed_t seed_t 256'h0A5CCCD9627BF6169B3A765D3D6D0CD89DBDCB7B6DF8D3C03746D60A0145D3ED
seed_t seed_t 256'h17B0AF865F8ACDDFC7580C2B7BC3FB33FC9BB5A4B292216C123ACF99A7861F96
LfsrWidth int 64 Default Lfsr configurations These LFSR parameters have been generated with $ util/design/gen-lfsr-seed.py --width 64 --seed 691876113 --prefix ""
lfsr_seed_t lfsr_seed_t 64'h22d326255bd24320
lfsr_perm_t lfsr_perm_t
RandWidth int LfsrWidth / 2 Random permutation
rand_perm_t rand_perm_t
AdvDataWidth int SwBindingWidth + 3*KeyWidth + DevIdWidth + HealthStateWidth Width calculations These are the largest calculations in use across all stages
IdDataWidth int KeyWidth
GenDataWidth int 32 + SaltWidth + KeyWidth*2 key version + salt + key ID + constant
StageWidth int $clog2(KeyMgrStages)
KDFMaxWidth int 1600 Max Payload Width to derivation function see security strength description https://keccak.team/keccak.html The max width here is chosen arbitrarily to ensure we do not get out of hand. Since KMAC is a MAC operation, the data can be as long as we need.
hw_key_req_t hw_key_req_t undefined

Types

Name Type Description
seed_t logic [KeyWidth-1:0] Default seeds These are generated using random.org byte dumper
lfsr_seed_t logic [LfsrWidth-1:0]
lfsr_perm_t logic [LfsrWidth-1:0][$clog2(LfsrWidth)-1:0]
rand_perm_t logic [RandWidth-1:0][$clog2(RandWidth)-1:0]
keymgr_stage_e enum logic [1:0] {
Creator = 0,
OwnerInt = 1,
Owner = 2,
Disable = 3 }		 Enumeration for operations
keymgr_key_dest_e enum logic [2:0] {
None,
Aes,
Kmac,
Otbn }		 Enumeration for sideload sel
keymgr_cnt_style_e enum logic {
CrossCnt,
DupCnt }		 Enumeration for hardened count style
keymgr_gen_out_e enum logic {
HwKey = 0,
SwKey = 1 }		 Enumeration for key select
keymgr_ops_e enum logic [2:0] {
OpAdvance = 0,
OpGenId = 1,
OpGenSwOut = 2,
OpGenHwOut = 3,
OpDisable = 4 }		 Enumeration for operation
keymgr_working_state_e enum logic [2:0] {
StReset,
StInit,
StCreatorRootKey,
StOwnerIntKey,
StOwnerKey,
StDisabled,
StInvalid }		 Enumeration for working state exposed to software
keymgr_op_status_e enum logic [1:0] {
OpIdle = 0,
OpWip = 1,
OpDoneSuccess = 2,
OpDoneFail = 3 }		 Enumeration for operation status
keymgr_sync_error_e enum logic [1:0] {
SyncErrInvalidOp,
SyncErrInvalidIn,
SyncErrLastIdx }		 keymgr has 4 categories of errors sync errors - recoverable errors that happen during keymgr operation async errors - recoverable errors that happen asynchronously sync faults - fatal errors that happen during keymgr operation async faults - fatal errors that happen asynchronously
keymgr_async_error_e enum logic [1:0] {
AsyncErrShadowUpdate,
AsyncErrLastIdx }
keymgr_sync_fault_e enum logic [1:0] {
SyncFaultKmacOp,
SyncFaultKmacOut,
SyncFaultLastIdx }
keymgr_async_fault_e enum logic [2:0] {
AsyncFaultKmacCmd,
AsyncFaultKmacFsm,
AsyncFaultRegIntg,
AsyncFaultShadow,
AsyncFaultFsmIntg,
AsyncFaultCntErr,
AsyncFaultLastIdx }
keymgr_err_pos_e enum logic [2:0] {
ErrInvalidOp,
ErrInvalidIn,
ErrShadowUpdate,
ErrLastPos }		 Bit position of error code Error is encoded as 1 error per bit
keymgr_fault_pos_e enum logic [3:0] {
FaultKmacCmd,
FaultKmacFsm,
FaultKmacOp,
FaultKmacOut,
FaultRegIntg,
FaultShadow,
FaultCtrlFsm,
FaultCtrlCnt,
FaultLastPos }		 Bit position of fault status
keymgr_key_update_e enum logic [2:0] {
KeyUpdateIdle,
KeyUpdateRandom,
KeyUpdateRoot,
KeyUpdateKmac,
KeyUpdateWipe }
keymgr_sideload_clr_e enum logic [2:0] {
SideLoadClrIdle,
SideLoadClrAes,
SideLoadClrKmac,
SideLoadClrOtbn }
hw_key_req_t struct packed {
logic valid;
logic [Shares-1:0][KeyWidth-1:0] key;
}		 Key connection to various symmetric modules
otbn_key_req_t struct packed {
logic valid;
logic [Shares-1:0][OtbnKeyWidth-1:0] key;
}		 Key connection to otbn
keymgr_lc_en_usage_e enum logic [1:0] {
KeyMgrEnCtrl,
KeyMgrEnCfgEn,
KeyMgrEnSwBindingEn,
KeyMgrEnLast }		 The following structs should be sourced from other modules defined here temporarily lc keymgr enable usage

Functions

Description
perm_data