Package: aes_pkg

File: aes_pkg.sv

Description

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

AES package

Constants

Name	Type	Value	Description
NumSharesKey	int unsigned	2
SliceSizeCtr	int unsigned	16	Software updates IV in chunks of 32 bits, the counter updates 16 bits at a time.
NumSlicesCtr	int unsigned	aes_reg_pkg::NumRegsIv * 32 / SliceSizeCtr
WidthPRDClearing	int unsigned	64	Widths of signals carrying pseudo-random data for clearing
NumChunksPRDClearing128	int unsigned	128/WidthPRDClearing
NumChunksPRDClearing256	int unsigned	256/WidthPRDClearing
WidthPRDSBox	int unsigned	8	Number PRD bits per S-Box. This includes the
WidthPRDData	int unsigned	16*WidthPRDSBox	16 S-Boxes for the data path
WidthPRDKey	int unsigned	4*WidthPRDSBox	4 S-Boxes for the key expand
WidthPRDMasking	int unsigned	WidthPRDData + WidthPRDKey
ChunkSizePRDMasking	int unsigned	WidthPRDMasking/5
ClearingLfsrWidth	int	64	Clearing PRNG default LFSR seed and permutation These LFSR parameters have been generated with $ util/design/gen-lfsr-seed.py --width 64 --seed 31468618 --prefix "Clearing"
clearing_lfsr_seed_t	clearing_lfsr_seed_t	64'hc32d580f74f1713a
clearing_lfsr_perm_t	clearing_lfsr_perm_t
clearing_lfsr_perm_t	clearing_lfsr_perm_t		A second permutation is needed for the second share.
MaskingLfsrWidth	int	160	= WidthPRDMasking = WidthPRDSBox * (16 + 4)
masking_lfsr_seed_t	masking_lfsr_seed_t	160'hc132b5723c5a4cf4743b3c7c32d580f74f1713a
MskgChunkLfsrWidth	int	32	= ChunkSizePRDMasking = WidthPRDMasking/5
mskg_chunk_lfsr_perm_t	mskg_chunk_lfsr_perm_t	160'heb3749dc187e7434d7f62a3d251e1c5b8cd10491
AES_MODE_WIDTH	int	6	Parameters used for controlgroups in the coverage
AES_KEYLEN_WIDTH	int	3
Mux2SelWidth	int	3	Generic, sparse mux selector encodings Encoding generated with: $ ./util/design/sparse-fsm-encode.py -d 3 -m 2 -n 3 \ -s 31468618 --language=sv Hamming distance histogram: 0: -- 1: -- 2: -- 3:
Mux3SelWidth	int	5	Encoding generated with: $ ./sparse-fsm-encode.py -d 3 -m 3 -n 5 \ -s 31468618 --language=sv Hamming distance histogram: 0: -- 1: -- 2: -- 3:
Mux4SelWidth	int	5	Encoding generated with: $ ./sparse-fsm-encode.py -d 3 -m 4 -n 5 \ -s 31468618 --language=sv Hamming distance histogram: 0: -- 1: -- 2: -- 3:
Mux6SelWidth	int	6	$ ./sparse-fsm-encode.py -d 3 -m 6 -n 6 \ -s 31468618 --language=sv Hamming distance histogram: 0: -- 1: -- 2: -- 3:
DIPSelNum	int	2	Mux selector signal types. These use the generic types defined above.
DIPSelWidth	int	Mux2SelWidth
SISelNum	int	2
SISelWidth	int	Mux2SelWidth
AddSISelNum	int	2
AddSISelWidth	int	Mux2SelWidth
StateSelNum	int	3
StateSelWidth	int	Mux3SelWidth
AddRKSelNum	int	3
AddRKSelWidth	int	Mux3SelWidth
KeyInitSelNum	int	2
KeyInitSelWidth	int	Mux2SelWidth
IVSelNum	int	6
IVSelWidth	int	Mux6SelWidth
KeyFullSelNum	int	4
KeyFullSelWidth	int	Mux4SelWidth
KeyDecSelNum	int	2
KeyDecSelWidth	int	Mux2SelWidth
KeyWordsSelNum	int	4
KeyWordsSelWidth	int	Mux4SelWidth
RoundKeySelNum	int	2
RoundKeySelWidth	int	Mux2SelWidth
AddSOSelNum	int	3
AddSOSelWidth	int	Mux3SelWidth
Sp2VNum	int	2	Sparse two-value signal type sp2v_e
Sp2VWidth	int	Mux2SelWidth

Types

Name	Type	Description
clearing_lfsr_seed_t	logic [ClearingLfsrWidth-1:0]
clearing_lfsr_perm_t	logic [ClearingLfsrWidth-1:0][$clog2(ClearingLfsrWidth)-1:0]
masking_lfsr_seed_t	logic [MaskingLfsrWidth-1:0]
mskg_chunk_lfsr_perm_t	logic [MskgChunkLfsrWidth-1:0][$clog2(MskgChunkLfsrWidth)-1:0]
sbox_impl_e	enum integer { SBoxImplLut, SBoxImplCanright, SBoxImplCanrightMasked, SBoxImplCanrightMaskedNoreuse, SBoxImplDom }
aes_op_e	enum logic { AES_ENC = 1'b0, AES_DEC = 1'b1 }
aes_mode_e	enum logic [AES_MODE_WIDTH-1:0] { AES_ECB = 6'b00_0001, AES_CBC = 6'b00_0010, AES_CFB = 6'b00_0100, AES_OFB = 6'b00_1000, AES_CTR = 6'b01_0000, AES_NONE = 6'b10_0000 }
ciph_op_e	enum logic { CIPH_FWD = 1'b0, CIPH_INV = 1'b1 }
key_len_e	enum logic [AES_KEYLEN_WIDTH-1:0] { AES_128 = 3'b001, AES_192 = 3'b010, AES_256 = 3'b100 }
status_t	struct packed { logic [31:7] unused; logic alert_fatal_fault; logic alert_recov_ctrl_update_err; logic input_ready; logic output_valid; logic output_lost; logic stall; logic idle; }
alert_test_t	struct packed { logic recov_ctrl_update_err; logic fatal_fault; }
mux2_sel_e	enum logic [Mux2SelWidth-1:0] { MUX2_SEL_0 = 3'b011, MUX2_SEL_1 = 3'b100 }
mux3_sel_e	enum logic [Mux3SelWidth-1:0] { MUX3_SEL_0 = 5'b01110, MUX3_SEL_1 = 5'b11000, MUX3_SEL_2 = 5'b00001 }
mux4_sel_e	enum logic [Mux4SelWidth-1:0] { MUX4_SEL_0 = 5'b01110, MUX4_SEL_1 = 5'b11000, MUX4_SEL_2 = 5'b00001, MUX4_SEL_3 = 5'b10111 }
mux6_sel_e	enum logic [Mux6SelWidth-1:0] { MUX6_SEL_0 = 6'b011101, MUX6_SEL_1 = 6'b110000, MUX6_SEL_2 = 6'b001000, MUX6_SEL_3 = 6'b000011, MUX6_SEL_4 = 6'b111110, MUX6_SEL_5 = 6'b100101 }
dip_sel_e	enum logic [DIPSelWidth-1:0] { DIP_DATA_IN = MUX2_SEL_0, DIP_CLEAR = MUX2_SEL_1 }
si_sel_e	enum logic [SISelWidth-1:0] { SI_ZERO = MUX2_SEL_0, SI_DATA = MUX2_SEL_1 }
add_si_sel_e	enum logic [AddSISelWidth-1:0] { ADD_SI_ZERO = MUX2_SEL_0, ADD_SI_IV = MUX2_SEL_1 }
state_sel_e	enum logic [StateSelWidth-1:0] { STATE_INIT = MUX3_SEL_0, STATE_ROUND = MUX3_SEL_1, STATE_CLEAR = MUX3_SEL_2 }
add_rk_sel_e	enum logic [AddRKSelWidth-1:0] { ADD_RK_INIT = MUX3_SEL_0, ADD_RK_ROUND = MUX3_SEL_1, ADD_RK_FINAL = MUX3_SEL_2 }
key_init_sel_e	enum logic [KeyInitSelWidth-1:0] { KEY_INIT_INPUT = MUX2_SEL_0, KEY_INIT_CLEAR = MUX2_SEL_1 }
iv_sel_e	enum logic [IVSelWidth-1:0] { IV_INPUT = MUX6_SEL_0, IV_DATA_OUT = MUX6_SEL_1, IV_DATA_OUT_RAW = MUX6_SEL_2, IV_DATA_IN_PREV = MUX6_SEL_3, IV_CTR = MUX6_SEL_4, IV_CLEAR = MUX6_SEL_5 }
key_full_sel_e	enum logic [KeyFullSelWidth-1:0] { KEY_FULL_ENC_INIT = MUX4_SEL_0, KEY_FULL_DEC_INIT = MUX4_SEL_1, KEY_FULL_ROUND = MUX4_SEL_2, KEY_FULL_CLEAR = MUX4_SEL_3 }
key_dec_sel_e	enum logic [KeyDecSelWidth-1:0] { KEY_DEC_EXPAND = MUX2_SEL_0, KEY_DEC_CLEAR = MUX2_SEL_1 }
key_words_sel_e	enum logic [KeyWordsSelWidth-1:0] { KEY_WORDS_0123 = MUX4_SEL_0, KEY_WORDS_2345 = MUX4_SEL_1, KEY_WORDS_4567 = MUX4_SEL_2, KEY_WORDS_ZERO = MUX4_SEL_3 }
round_key_sel_e	enum logic [RoundKeySelWidth-1:0] { ROUND_KEY_DIRECT = MUX2_SEL_0, ROUND_KEY_MIXED = MUX2_SEL_1 }
add_so_sel_e	enum logic [AddSOSelWidth-1:0] { ADD_SO_ZERO = MUX3_SEL_0, ADD_SO_IV = MUX3_SEL_1, ADD_SO_DIP = MUX3_SEL_2 }
sp2v_e	enum logic [Sp2VWidth-1:0] { SP2V_HIGH = MUX2_SEL_0, SP2V_LOW = MUX2_SEL_1 }
ctrl_reg_t	struct packed { logic force_zero_masks; logic manual_operation; key_len_e key_len; aes_mode_e mode; aes_op_e operation; }	Control register type

Functions

aes_mul2 (logic [7:0]) return (logic [7:0])

Description
Multiplication by {02} (i.e. x) on GF(2^8)
with field generating polynomial {01}{1b} (9'h11b)
Sometimes also denoted by xtime().

aes_mul4 (logic [7:0]) return (logic [7:0])

Description
Multiplication by {04} (i.e. x^2) on GF(2^8)
with field generating polynomial {01}{1b} (9'h11b)

aes_div2 (logic [7:0]) return (logic [7:0])

Description
Division by {02} (i.e. x) on GF(2^8)
with field generating polynomial {01}{1b} (9'h11b)
This is the inverse of aes_mul2() or xtime().

aes_circ_byte_shift (logic [31:0] in,
logic [1:0]) return (logic [31:0])

Description
Circular byte shift to the left

aes_transpose (logic [3:0][3:0][7:0]) return (logic [3:0][3:0][7:0])

Description
Transpose state matrix

aes_col_get (logic [3:0][3:0][7:0] in,
logic [1:0]) return (logic [3:0][7:0])

Description
Extract single column from state matrix

aes_mvm (logic [7:0] vec_b,
) return (logic [7:0])

Description
Matrix-vector multiplication in GF(2^8): c = A * b

aes_prd_get_lsbs (logic [(4*WidthPRDSBox)-1:0]) return (logic [3:0][7:0])

Description
Function for extracting LSBs of the per-S-Box pseudo-random data (PRD) from the output of the
masking PRNG.

The masking PRNG is used for generating both the PRD for the S-Boxes/SubBytes operation as
well as for the input data masks. When using any of the masked Canright S-Box implementations,
it is important that the SubBytes input masks (generated by the PRNG in Round X-1) and the
SubBytes output masks (generated by the PRNG in Round X) are independent. Inside the PRNG,
this is achieved by using multiple, separately re-seeded LFSR chunks and by selecting the
separate LFSR chunks in alternating fashion. Since the input data masks become the SubBytes
input masks in the first round, we select the same 8 bit lanes for the input data masks which
are also used to form the SubBytes output mask for the masked Canright S-Box implementations,
i.e., the 8 LSBs of the per S-Box PRD. In particular, we have:

prng_output = { prd_key_expand, … , sb_prd[4], sb_out_mask[4], sb_prd[0], sb_out_mask[0] }

Where sb_out_mask[x] contains the SubBytes output mask for byte x (when using a masked
Canright S-Box implementation) and sb_prd[x] contains additional PRD consumed by SubBytes for
byte x.

When using a masked S-Box implementation other than Canright, we still select the 8 LSBs of
the per-S-Box PRD to form the input data mask of the corresponding byte. We do this to
distribute the input data masks over all LFSR chunks of the masking PRNG.
For one row of the state matrix, extract the 8 LSBs of the per-S-Box PRD from the PRNG output.
These bits are used as:

input data masks, and
SubBytes output mask when using a masked Canright S-Box implementation.