| // Copyright lowRISC contributors. |
| // Licensed under the Apache License, Version 2.0, see LICENSE for details. |
| // SPDX-License-Identifier: Apache-2.0 |
| |
| { name: "kmac" |
| clocking: [ |
| {clock: "clk_i", reset: "rst_ni", idle: "idle_o", primary: true}, |
| {clock: "clk_edn_i", reset: "rst_edn_ni", idle: "idle_o"} |
| ] |
| bus_interfaces: [ |
| { protocol: "tlul", direction: "device" } |
| ], |
| |
| interrupt_list: [ |
| { name: "kmac_done" |
| desc: "KMAC/SHA3 absorbing has been completed" |
| } |
| { name: "fifo_empty" |
| desc: "Message FIFO empty condition" |
| } |
| { name: "kmac_err" |
| desc: "KMAC/SHA3 error occurred. ERR_CODE register shows the details" |
| } |
| ] |
| alert_list: [ |
| { name: "recov_operation_err" |
| desc: ''' |
| Alert for KMAC operation error. It occurs when the shadow registers have update errors. |
| ''' |
| } |
| { name: "fatal_fault_err", |
| desc: ''' |
| This fatal alert is triggered when a fatal error is detected inside the KMAC unit. |
| Examples for such faults include: |
| i) TL-UL bus integrity fault. |
| ii) Storage errors in the shadow registers. |
| iii) Errors in the message, round, or key counter. |
| iv) Any internal FSM entering an invalid state. |
| v) An error in the redundant lfsr. |
| The KMAC unit cannot recover from such an error and needs to be reset. |
| ''' |
| } |
| ], |
| param_list: [ |
| { name: "EnMasking" |
| type: "bit" |
| default: "1" |
| desc: ''' |
| Disable(0) or enable(1) first-order masking of Keccak round. |
| ''' |
| local: "false" |
| expose: "true" |
| } |
| { name: "SecCmdDelay" |
| type: "int" |
| default: "0" |
| desc: ''' |
| Command delay, useful for SCA measurements only. |
| A value of e.g. 40 allows the processor to go into sleep before KMAC starts operation. |
| If a value greater than 0 is chosen, software can pass two commands in series. |
| The second command is buffered internally and will be presented to the hardware SecCmdDelay number of cycles after the first one. |
| ''' |
| local: "false" |
| expose: "true" |
| } |
| { name: "SecIdleAcceptSwMsg" |
| type: "bit" |
| default: "0" |
| desc: ''' |
| If enabled (1), software writes to the message FIFO before having received a START command are not ignored. |
| Disabled (0) by default. |
| Useful for SCA measurements only. |
| ''' |
| local: "false" |
| expose: "true" |
| } |
| { name: "NumWordsKey" |
| type: "int" |
| default: "16" |
| desc: "Number of words for the secret key" |
| local: "true" |
| } |
| { name: "NumWordsPrefix" |
| type: "int" |
| default: "11" |
| desc: "Number of words for Encoded NsPrefix." |
| local: "true" |
| } |
| { name: "HashCntW" |
| type: "int unsigned" |
| default: "10" |
| desc: "Width of the hash counter in the entropy" |
| local: "true" |
| } |
| { name: "NumSeedsEntropyLfsr", |
| type: "int", |
| default: "5", |
| desc: "Number of words for the LFSR seed used for entropy generation", |
| local: "true" |
| } |
| { name: "RndCnstLfsrSeed" |
| desc: "Compile-time random data for LFSR default seed" |
| type: "kmac_pkg::lfsr_seed_t" |
| randcount: "800" |
| randtype: "data" |
| } |
| { name: "RndCnstLfsrPerm", |
| desc: "Compile-time random permutation for LFSR output", |
| type: "kmac_pkg::lfsr_perm_t" |
| randcount: "800", |
| randtype: "perm", |
| } |
| { name: "RndCnstLfsrFwdPerm", |
| desc: "Compile-time random permutation for forwarding LFSR state", |
| type: "kmac_pkg::lfsr_fwd_perm_t" |
| randcount: "32", |
| randtype: "perm", |
| } |
| { name: "RndCnstMsgPerm" |
| desc: "Compile-time random permutation for LFSR Message output" |
| type: "kmac_pkg::msg_perm_t" |
| randcount: "64" |
| randtype: "perm" |
| } |
| ] |
| inter_signal_list: [ |
| { struct: "hw_key_req" |
| type: "uni" |
| name: "keymgr_key" |
| act: "rcv" |
| package: "keymgr_pkg" |
| } |
| { struct: "app" |
| type: "req_rsp" |
| name: "app" |
| act: "rsp" |
| package: "kmac_pkg" |
| width: "3" |
| } |
| { struct: "edn" |
| type: "req_rsp" |
| name: "entropy" |
| act: "req" |
| width: "1" |
| package: "edn_pkg" |
| } |
| { name: "idle", |
| type: "uni", |
| act: "req", |
| package: "prim_mubi_pkg", |
| struct: "mubi4", |
| width: "1" |
| } |
| { struct: "logic" |
| type: "uni" |
| name: "en_masking" |
| act: "req" |
| } |
| { struct: "lc_tx" |
| type: "uni" |
| name: "lc_escalate_en" |
| act: "rcv" |
| default: "lc_ctrl_pkg::Off" |
| package: "lc_ctrl_pkg" |
| } |
| ] |
| countermeasures: [ |
| { name: "BUS.INTEGRITY", |
| desc: "End-to-end bus integrity scheme." |
| } |
| { name: "LC_ESCALATE_EN.INTERSIG.MUBI" |
| desc: "The global escalation input signal from the life cycle is multibit encoded" |
| } |
| { name: "SW_KEY.KEY.MASKING" |
| desc: '''Data storage and secret key are two share to guard against 1st |
| order attack.''' |
| } |
| { name: "KEY.SIDELOAD" |
| desc: "Key from KeyMgr is sideloaded." |
| } |
| { name: "CFG_SHADOWED.CONFIG.SHADOW" |
| desc: "Shadowed CFG register." |
| } |
| { name: "FSM.SPARSE" |
| desc: "FSMs in KMAC are sparsely encoded." |
| } |
| { name: "CTR.REDUN" |
| desc: '''Round counter, key index counter, sentmsg counter and hash counter |
| use prim_count for redundancy''' |
| } |
| { name: "CFG_SHADOWED.CONFIG.REGWEN" |
| desc: "CFG_SHADOWED is protected by REGWEN" |
| } |
| { name: "FSM.GLOBAL_ESC" |
| desc: "Escalation moves all sparse FSMs into an invalid state." |
| } |
| { name: "FSM.LOCAL_ESC" |
| desc: "Local fatal faults move all sparse FSMs into an invalid state." |
| } |
| { name: "LOGIC.INTEGRITY" |
| desc: "The reset net for the internal state register and critical nets around the output register are buried." |
| } |
| ] |
| regwidth: "32" |
| registers: [ |
| { name: "CFG_REGWEN" |
| desc: '''Controls the configurability of !!CFG register. |
| |
| This register ensures the contents of !!CFG register cannot be |
| changed by the software while the KMAC/SHA3 is in operation mode. |
| ''' |
| swaccess: "ro" |
| hwaccess: "hwo" |
| hwext: "true" |
| fields: [ |
| { bits: "0" |
| name: "en" |
| desc: "Configuration enable." |
| resval: "1" |
| } // f : en |
| ] |
| tags: [// This regwen is completely under HW management and thus cannot be manipulated |
| // by software. |
| "excl:CsrNonInitTests:CsrExclCheck"] |
| } // R : CFG_REGWEN |
| { name: "CFG_SHADOWED" |
| desc: '''KMAC Configuration register. |
| |
| This register is updated when the hashing engine is in Idle. |
| If the software updates the register while the engine computes, the |
| updated value will be discarded. |
| ''' |
| regwen: "CFG_REGWEN" |
| swaccess: "rw" |
| hwaccess: "hro" |
| shadowed: "true" |
| hwqe: "true" |
| update_err_alert: "recov_operation_err" |
| storage_err_alert: "fatal_fault_err" |
| fields: [ |
| { bits: "0" |
| name: "kmac_en" |
| desc: '''KMAC datapath enable. |
| |
| If this bit is 1, the incoming message is processed in KMAC |
| with the secret key. |
| ''' |
| tags: [// don't enable kmac and sha data paths - we will do that in functional tests |
| "excl:CsrNonInitTests:CsrExclWrite", |
| "shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_kmac_en" |
| ] |
| } // f: kmac_en |
| { bits: "3:1" |
| name: "kstrength" |
| desc: '''Hashing Strength |
| |
| 3 bit field to select the security strength of SHA3 hashing |
| engine. If mode field is set to SHAKE or cSHAKE, only 128 and |
| 256 strength can be selected. Other value will result error |
| when hashing starts. |
| ''' |
| enum: [ |
| { value: "0" |
| name: "L128" |
| desc: "128 bit strength. Keccak rate is 1344 bit" |
| } |
| { value: "1" |
| name: "L224" |
| desc: "224 bit strength. Keccak rate is 1152 bit" |
| } |
| { value: "2" |
| name: "L256" |
| desc: "256 bit strength. Keccak rate is 1088 bit" |
| } |
| { value: "3" |
| name: "L384" |
| desc: "384 bit strength. Keccak rate is 832 bit" |
| } |
| { value: "4" |
| name: "L512" |
| desc: "512 bit strength. Keccak rate is 576 bit" |
| } |
| ] |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_kstrength"] |
| } // f: strength |
| { bits: "5:4" |
| name: "mode" |
| desc: '''Keccak hashing mode. |
| |
| This module supports SHA3 main hashing algorithm and the part |
| of its derived functions, SHAKE and cSHAKE with limitations. |
| This field is to select the mode. |
| ''' |
| enum: [ |
| { value: "0" |
| name: "SHA3" |
| desc: "SHA3 hashing mode. It appends `2'b 10` to the end of msg" |
| } |
| { value: "2" |
| name: "SHAKE" |
| desc: "SHAKE hashing mode. It appends `1111` to the end of msg" |
| } |
| { value: "3" |
| name: "cSHAKE" |
| desc: "cSHAKE hashing mode. It appends `00` to the end of msg" |
| } |
| ] |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_mode"] |
| } // f: mode |
| { bits: "8" |
| name: "msg_endianness" |
| desc: '''Message Endianness. |
| |
| If 1 then each individual multi-byte value, regardless of its |
| alignment, written to !!MSG_FIFO will be added to the message |
| in big-endian byte order. |
| If 0, each value will be added to the message in little-endian |
| byte order. |
| A message written to !!MSG_FIFO one byte at a time will not be |
| affected by this setting. |
| From a hardware perspective byte swaps are performed on a TL-UL |
| word granularity. |
| ''' |
| resval: "0" |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_msg_endianness"] |
| } // f: msg_endianness |
| { bits: "9" |
| name: "state_endianness" |
| desc: '''State Endianness. |
| |
| If 1 then each individual word in the !!STATE output register |
| is converted to big-endian byte order. |
| The order of the words in relation to one another is not |
| changed. |
| This setting does not affect how the state is interpreted |
| during computation. |
| ''' |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_state_endianness"] |
| } // f: state_endianness |
| { bits: "12" |
| name: "sideload" |
| desc: '''Sideloaded Key. |
| |
| If 1, KMAC uses KeyMgr sideloaded key for SW initiated KMAC |
| operation. KMAC uses the sideloaded key regardless of this |
| configuration when KeyMgr initiates the KMAC operation for |
| Key Derivation Function (KDF). |
| ''' |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_sideload"] |
| } // f: sideload |
| { bits: "17:16" |
| name: entropy_mode |
| desc: '''Entropy Mode |
| |
| Software selects the entropy source with this field. In EdnMode, |
| the entropy generator sends requests to EDN to get the entropy. The |
| received entropy is fed into internal LFSR. |
| |
| In SwMode, the software should update the internal LFSR seed |
| through !!ENTROPY_SEED_0 etc. |
| |
| Out of the reset, the entropy module inside KMAC IP generates LFSR to |
| support the ROM_CTRL operation. The logic does not go back to the |
| reset state to prevent KMAC from using LFSR with seeds. SW must |
| configure correct entropy_mode prior to setting the entropy_ready. |
| ''' |
| |
| enum: [ |
| { value: "0" |
| name: "idle_mode" |
| desc: '''At reset state, the entropy mode is Idle mode. It does |
| not operate in this mode. |
| ''' |
| } |
| { value: "1" |
| name: "edn_mode" |
| desc: "Entropy generator module fetches entropy from EDN" |
| } |
| { value: "2" |
| name: "sw_mode" |
| desc: '''Software update the internal entropy via register |
| interface''' |
| } |
| ] |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_entropy_mode"] |
| } // f: entropy_mode |
| { bits: "19" |
| name: entropy_fast_process |
| desc: '''Entropy Fast process mode. |
| |
| If 1, entropy logic uses garbage data while not processing the KMAC |
| key block. It will re-use previous entropy value and will not |
| expand the entropy when it is consumed. Only it refreshes the |
| entropy while processing the secret key block. |
| ''' |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_entropy_fast_process"] |
| } // f: entropy_fast_process |
| { bits: "20" |
| name: msg_mask |
| desc: '''Message Masking with PRNG. |
| |
| If 1, KMAC applies PRNG to the input messages to the Keccak module |
| when KMAC mode is on. |
| ''' |
| } // f: msg_mask |
| { bits: "24" |
| name: entropy_ready |
| desc: '''Entropy Ready status. |
| |
| Software sets this field to allow the entropy generator in KMAC to |
| fetch the entropy and run. |
| ''' |
| tags: [// Randomly write mem will cause this reg updated by design |
| "excl:CsrAllTests:CsrExclWrite", |
| "shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_entropy_ready"] |
| } // f: entropy_ready |
| { bits: "25" |
| name: err_processed |
| desc: '''When error occurs and one of the state machine stays at |
| Error handling state, SW may process the error based on |
| ERR_CODE, then let FSM back to the reset state |
| ''' |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_err_processed"] |
| } // f: err_processed |
| { bits: "26" |
| name: en_unsupported_modestrength |
| desc: '''Enable Unsupported Mode and Strength configs. |
| |
| SW may set this field for KMAC to move forward with unsupported |
| Keccak Mode and Strength configurations, such as cSHAKE512. |
| |
| If not set, KMAC won't propagate the SW command (CmdStart) to the |
| rest of the blocks (AppIntf, KMAC Core, SHA3). |
| ''' |
| tags: [// Randomly write mem will cause this reg updated by design |
| "excl:CsrAllTests:CsrExclWrite", |
| "shadowed_reg_path:u_cfg_reg_shadowed.u_cfg_reg_shadowed_en_unsupported_modestrength"] |
| } // f: en_unsupported_modestrength |
| ] |
| tags: ["shadowed_reg_path:u_cfg_reg_shadowed"] |
| } // R: CFG |
| { name: "CMD" |
| desc: '''KMAC/ SHA3 command register. |
| |
| This register is to control the KMAC to start accepting message, |
| to process the message, and to manually run additional keccak |
| rounds at the end. Only at certain stage, the CMD affects to the |
| control logic. It follows the sequence of |
| |
| `start` --> `process` --> {`run` if needed --> } `done` |
| ''' |
| swaccess: "r0w1c" |
| hwaccess: "hro" |
| hwext: "true" |
| hwqe: "true" |
| tags: [// design assertion : after start sets, can only wr msg or set process |
| // design assertion : process can be set only after start is set |
| "excl:CsrAllTests:CsrExclWrite"] |
| fields: [ |
| { bits: "3:0" |
| name: "cmd" |
| desc: '''Issue a command to the KMAC/SHA3 IP. To prevent sw from |
| writing multiple bits at once, the field is defined as enum. |
| ''' |
| enum: [ |
| { value: "1" |
| name: "start" |
| desc: '''If writes 1 into this field when KMAC/SHA3 is in idle, |
| KMAC/SHA3 begins its operation. |
| |
| If the mode is cSHAKE, before receiving the message, the |
| hashing logic processes Function name string N and |
| customization input string S first. If KMAC mode is enabled, |
| additionally it processes secret key block. |
| ''' |
| } // e: start |
| { value: "2" |
| name: "process" |
| desc: '''If writes 1 into this field when KMAC/SHA3 began its |
| operation and received the entire message, it computes the |
| digest or signing. |
| ''' |
| } // e: process |
| { value: "4" |
| name: "run" |
| desc: '''The `run` field is used in the sponge squeezing stage. |
| It triggers the keccak round logic to run full 24 rounds. |
| This is optional and used when software needs more digest |
| bits than the keccak rate. |
| |
| It only affects when the kmac/sha3 operation is completed. |
| ''' |
| } // e: run |
| { value: "8" |
| name: "done" |
| desc: '''If writes 1 into this field when KMAC/SHA3 squeezing is |
| completed. KMAC/SHA3 hashing engine clears internal |
| variables and goes back to Idle state for next command. |
| ''' |
| } // e: done |
| ] // enum |
| } // f: cmd |
| { bits: "8" |
| name: "entropy_req" |
| desc: '''SW triggered Entropy Request |
| |
| If writes 1 to this field |
| ''' |
| } // f: entropy_req |
| { bits: "9" |
| name: "hash_cnt_clr" |
| desc: "If writes 1, it clears the hash (KMAC) counter in the entropy module" |
| } |
| ] |
| } // R: CMD |
| { name: "STATUS" |
| desc: '''KMAC/SHA3 Status register.''' |
| swaccess: "ro" |
| hwaccess: "hwo" |
| hwext: "true" |
| fields: [ |
| { bits: "0" |
| name: "sha3_idle" |
| desc: "If 1, SHA3 hashing engine is in idle state." |
| resval: "1" |
| } |
| { bits: "1" |
| name: "sha3_absorb" |
| desc: "If 1, SHA3 is receiving message stream and processing it" |
| } |
| { bits: "2" |
| name: "sha3_squeeze" |
| desc: '''If 1, SHA3 completes sponge absorbing stage. |
| In this stage, SW can manually run the hashing engine. |
| ''' |
| } |
| { bits: "12:8" |
| name: "fifo_depth" |
| desc: "Message FIFO entry count" |
| } |
| { bits: "14" |
| name: "fifo_empty" |
| desc: "Message FIFO Empty indicator" |
| resval: "1" |
| } |
| { bits: "15" |
| name: "fifo_full" |
| desc: "Message FIFO Full indicator" |
| } |
| { bits: "16", |
| name: "ALERT_FATAL_FAULT", |
| resval: "0", |
| desc: ''' |
| No fatal fault has occurred inside the KMAC unit (0). |
| A fatal fault has occured and the KMAC unit needs to be reset (1), |
| Examples for such faults include |
| i) TL-UL bus integrity fault |
| ii) storage errors in the shadow registers |
| iii) errors in the message, round, or key counter |
| iv) any internal FSM entering an invalid state |
| v) an error in the redundant lfsr |
| ''' |
| } |
| { bits: "17", |
| name: "ALERT_RECOV_CTRL_UPDATE_ERR", |
| resval: "0", |
| desc: ''' |
| An update error has not occurred (0) or has occured (1) in the shadowed Control Register. |
| KMAC operation needs to be restarted by re-writing the Control Register. |
| ''' |
| } |
| ] |
| } // R: STATUS |
| { name: "ENTROPY_PERIOD" |
| desc: '''Entropy Timer Periods. |
| ''' |
| swaccess: "rw" |
| hwaccess: "hro" |
| regwen: "CFG_REGWEN" |
| fields: [ |
| { bits: "9:0" |
| name: "prescaler" |
| desc: '''EDN Wait timer prescaler. |
| |
| EDN Wait timer has 16 bit value. The timer value is increased when the timer pulse is generated. Timer pulse is raises when the number of the clock cycles hit this prescaler value. |
| |
| The exact period of the timer pulse is unknown as the KMAC input clock may contain jitters. |
| ''' |
| } |
| { bits: "31:16" |
| name: "wait_timer" |
| desc: '''EDN request wait timer. |
| |
| The entropy module in KMAC waits up to this field in the timer pulse |
| after it sends request to EDN module. If the timer expires, the |
| entropy module moves to an error state and notifies to the system. |
| |
| If 0, the entropy module waits the EDN response always. If EDN does |
| not respond in this configuration, the software shall reset the IP. |
| ''' |
| tags: [// Writing this timer may cause EDN wait timeout, which triggers a SVA error |
| // We will do that in functional tests |
| "excl:CsrNonInitTests:CsrExclWrite"] |
| } |
| ] |
| } // R: ENTROPY_PERIOD |
| { |
| name: "ENTROPY_REFRESH_HASH_CNT" |
| desc: '''Entropy Refresh Counter |
| |
| KMAC entropy can be refreshed after the given threshold KMAC operations |
| run. If the KMAC hash counter !!ENTROPY_REFRESH_HASH_CNT hits (GTE) the |
| configured threshold !!ENTROPY_REFRESH_THRESHOLD_SHADOWED, the entropy |
| module in the KMAC IP requests new seed to EDN and reset the KMAC |
| hash counter. |
| |
| If the threshold is 0, the refresh by the counter does not work. And the |
| counter is only reset by the CMD.hash_cnt_clr CSR bit. |
| ''' |
| swaccess: "ro" |
| hwaccess: "hwo" |
| regwen: "CFG_REGWEN" |
| fields: [ |
| { bits: "HashCntW-1:0" |
| name: "hash_cnt" |
| desc: "Hash (KMAC) counter" |
| } |
| ] |
| } // R: ENTROPY_REFRESH_HASH_CNT |
| { |
| name: "ENTROPY_REFRESH_THRESHOLD_SHADOWED" |
| desc: '''Entropy Refresh Threshold |
| |
| KMAC entropy can be refreshed after the given threshold KMAC operations |
| run. If the KMAC hash counter !!ENTROPY_REFRESH_HASH_CNT hits (GTE) the |
| configured threshold !!ENTROPY_REFRESH_THRESHOLD_SHADOWED, the entropy |
| module in the KMAC IP requests new seed to EDN and reset the KMAC |
| hash counter. |
| |
| If the threshold is 0, the refresh by the counter does not work. And the |
| counter is only reset by the CMD.hash_cnt_clr CSR bit. |
| ''' |
| swaccess: "rw" |
| hwaccess: "hro" |
| regwen: "CFG_REGWEN" |
| shadowed: "true" |
| update_err_alert: "recov_operation_err" |
| storage_err_alert: "fatal_fault_err" |
| fields: [ |
| { bits: "HashCntW-1:0" |
| name: "threshold" |
| desc: "Hash Threshold" |
| } |
| ] |
| } // R: ENTROPY_REFRESH_THRESHOLD_SHADOWED |
| { multireg: { |
| name: "ENTROPY_SEED" |
| desc: '''Entropy Seed |
| |
| Entropy seed registers for the integrated entropy generator. |
| |
| If !!CFG_SHADOWED.entropy_mode is set to sw_mode, software first needs to set |
| !!CFG_SHADOWED.entropy_ready and then write the !!ENTROPY_SEED_0 - |
| !!ENTROPY_SEED_4 registers in ascending order. Software writes one 32-bit value |
| to every register which is subsequently loaded into the corresponding 32-bit LFSR |
| chunk of the entropy generator. |
| |
| After writing all !!ENTROPY_SEED_0 registers, the entropy generator will start |
| its operation. After this point, writing these registers has no longer any |
| effect. |
| ''' |
| count: "NumSeedsEntropyLfsr" |
| cname: "KMAC" |
| hwext: "true" |
| hwqe : "true" |
| regwen: "CFG_REGWEN" |
| swaccess: "wo" |
| hwaccess: "hro" |
| fields: [ |
| { bits: "31:0" |
| name: "seed" |
| desc: "32-bit chunk of the entropy generator seed" |
| } |
| ] |
| } // R: ENTROPY_SEED |
| } // multireg: ENTROPY_SEED |
| { multireg: { |
| name: "KEY_SHARE0" |
| desc: '''KMAC Secret Key |
| |
| KMAC secret key can be up to 512 bit. |
| Order of the secret key is: |
| key[512:0] = {KEY15, KEY14, ... , KEY0}; |
| |
| The registers are allowed to be updated when the engine is in Idle state. |
| If the engine computes the hash, it discards any attempts to update the secret keys |
| and report an error. |
| |
| Current KMAC supports up to 512 bit secret key. It is the sw |
| responsibility to keep upper bits of the secret key to 0. |
| ''' |
| count: "NumWordsKey" |
| cname: "KMAC" |
| hwext: "true" |
| hwqe : "true" |
| swaccess: "wo" |
| hwaccess: "hro" |
| regwen: "CFG_REGWEN" |
| fields: [ |
| { bits: "31:0" |
| name: "key" |
| desc: "32-bit chunk of up-to 512-bit Secret Key" |
| } |
| ] |
| } // R: KEY_SHARE0 |
| } // multireg: KEY_SHARE0 |
| { multireg: { |
| name: "KEY_SHARE1" |
| desc: '''KMAC Secret Key, 2nd share. |
| |
| KMAC secret key can be up to 512 bit. |
| Order of the secret key is: |
| key[512:0] = {KEY15, KEY14, ... , KEY0}; |
| |
| The registers are allowed to be updated when the engine is in Idle state. |
| If the engine computes the hash, it discards any attempts to update the secret keys |
| and report an error. |
| |
| Current KMAC supports up to 512 bit secret key. It is the sw |
| responsibility to keep upper bits of the secret key to 0. |
| ''' |
| count: "NumWordsKey" |
| cname: "KMAC" |
| hwext: "true" |
| hwqe : "true" |
| swaccess: "wo" |
| hwaccess: "hro" |
| regwen: "CFG_REGWEN" |
| fields: [ |
| { bits: "31:0" |
| name: "key" |
| desc: "32-bit chunk of up-to 512-bit Secret Key" |
| } |
| ] |
| } // R: KEY_SHARE1 |
| } // multireg: KEY_SHARE1 |
| { name: "KEY_LEN" |
| desc: '''Secret Key length in bit. |
| |
| This value is used to make encoded secret key in KMAC. |
| KMAC supports certain lengths of the secret key. Currently it |
| supports 128b, 192b, 256b, 384b, and 512b secret keys. |
| ''' |
| regwen: "CFG_REGWEN" |
| swaccess: "wo" |
| hwaccess: "hro" |
| hwext: "false" |
| fields: [ |
| { bits: "2:0" |
| name: "len" |
| desc: "Key length choice" |
| enum: [ |
| { value: "0" |
| name: "Key128" |
| desc: "Key length is 128 bit." |
| } |
| { value: "1" |
| name: "Key192" |
| desc: "Key length is 192 bit." |
| } |
| { value: "2" |
| name: "Key256" |
| desc: "Key length is 256 bit." |
| } |
| { value: "3" |
| name: "Key384" |
| desc: "Key length is 384 bit." |
| } |
| { value: "4" |
| name: "Key512" |
| desc: "Key length is 512 bit." |
| } |
| ] |
| } // f : len |
| ] |
| } // R : KEY_LEN |
| { multireg: { |
| name: "PREFIX" |
| desc: '''cSHAKE Prefix register. |
| |
| Prefix including Function Name N and Customization String S. |
| The SHA3 assumes this register value is encoded as: |
| `encode_string(N) || encode_string(S) || 0`. It means that the |
| software can freely decide the length of N or S based on the |
| given Prefix register size 320bit. 320bit is determined to have |
| 32-bit of N and up to 256-bit of S + encode of their length. |
| |
| It is SW responsibility to fill the register with encoded value |
| that is described at Section 2.3.2 String Encoding in NIST SP |
| 800-185 specification. |
| |
| Order of Prefix is: |
| prefix[end:0] := {PREFIX(N-1), ..., PREFIX(1), PREFIX(0) } |
| |
| The registers are allowed to be updated when the engine is in Idle state. |
| If the engine computes the hash, it discards any attempts to update the secret keys |
| and report an error. |
| ''' |
| count: "NumWordsPrefix" |
| cname: "KMAC" |
| hwext: "false" |
| swaccess: "rw" |
| hwaccess: "hro" |
| regwen: "CFG_REGWEN" |
| fields: [ |
| { bits: "31:0" |
| name: "prefix" |
| desc: "32-bit chunk of Encoded NS Prefix" |
| } |
| ] |
| } // R: PREFIX |
| } // multireg: PREFIX |
| { name: "ERR_CODE" |
| desc: "KMAC/SHA3 Error Code", |
| swaccess: "ro", |
| hwaccess: "hwo", |
| fields: [ |
| { bits: "31:0", |
| name: "err_code", |
| desc: '''If error interrupt occurs, this register has information of error cause. |
| Please take a look at `hw/ip/kmac/rtl/kmac_pkg.sv:err_code_e enum type. |
| ''' |
| tags: [// Randomly write mem will cause this reg updated by design |
| "excl:CsrNonInitTests:CsrExclWriteCheck"] |
| } |
| ] |
| } // R: ERR_CODE |
| { skipto: "0x400"} |
| { window: { |
| name: "STATE" |
| items: "128" // 512B address space |
| swaccess: "ro" |
| desc: '''Keccak State (1600 bit) memory. |
| |
| The software can get the processed digest by reading this memory |
| region. Unlike MSG_FIFO, STATE memory space sees the addr[9:0]. |
| If Masking feature is enabled, the software reads two shares from |
| this memory space. |
| |
| 0x400 - 0x4C7: State share |
| 0x500 - 0x5C7: Mask share of the state, 0 if EnMasking = 0 |
| ''' |
| } |
| } // W: STATE |
| |
| { skipto: "0x800"} |
| |
| { window: { |
| name: "MSG_FIFO" |
| items: "512" // 2kB range |
| swaccess: "wo" |
| byte-write: "true" |
| desc: '''Message FIFO. |
| |
| Any write to this window will be appended to the FIFO. Only lower |
| 2 bits `[1:0]` of the address matter to writes within the window |
| in order to handle with sub-word writes. |
| ''' |
| } |
| } // W: MSG_FIFO |
| ] |
| } |
