WBMatrix

An Optimized Matrix Library for White-Box White-Box Block Cipher Implementations

Contains the matrix operations and test cases related to white-box block cipher implementation and provides the Chow et al.'s White-box AES and Xiao-Lai's white-box SM4 built by WBMatrix, NTL, and M4RI, respectively.

Supports For Following Operations (8/16/32/64/128 bits):

• Matrix-Vector multiplication
  
• Matrix-Matrix multiplication
  
• Generation of an invertible Matrix with it's inverse matrix (pairwise invertible matrices)
  
• Generation of pairwise invertible affine transformations
  
• Matrix transpositon
  
• Affine transformation
  
• Encodings concatenation
  
• Encodings conversion
  

Header Files:

• inverse.h Revisable generate times from the temporary state matrix , the selection times for initialization of base matrix.
  
• WBMatrix.h The declaration of the main function.
  
• struture.h Data structure of matrix.
  
• random.h For random functions.
  

Main Functions (8bit in Example):

• initinvbaseM8(int N) initial intermediate matrix which generate in N times from an identity matrix.
  we give a suggestion for the selection of N in inverse.h.
  
• genMatpairM8(M8 *Mat, M8 *Mat_inv) generate an invertible matrix Mat and its inverse matrix Mat_inv from the intermediate matrix with prestored operating times set in inverse.h.
  
• genaffinepairM8(Aff8 *aff, Aff8 *aff_inv) generate an affine transformation aff and its inverse affine transformation aff_inv.
  
• MatMulVecM8(M8 Mat, V8 Vec, V8 *ans) multiplication for matrix Mat and vertor Vec, result set in ans.
  
• MatMulMatM8(M8 Mat1, M8 Mat2, M8 *Mat) multiplication for matrix Mat1 and matrix Mat2, result set in Mat.
  
• MattransM8(M8 Mat, M8 *Mat_trans) transpositon for matrix Mat, result set in Mat_trans.
  
• affineU8(Aff8 aff, uint8_t arr) affine transformation for an uint8_t number, and return an uint8_t result.
• affinemixM8(Aff8 aff, Aff8 preaff_inv, Aff8 *mixaff) affine conversion between aff and preaff_inv, result set in mixaff.
• affinecomM8to32(Aff8 aff1, Aff8 aff2, Aff8 aff3, Aff8 aff4, Aff32 *aff) affine concatenation, the matrix part of aff consists of sub-matrix on its diagonal, while the vector part of aff consists of sub-vector.

Example:

M32 mat32[3]; //define a 32-bit matrix
initinvbaseM32(initM32_max); //initial the intermediate matrix
genMatpairM32(&mat32[0],&mat32[1]); //generate pairwise invertible matrices
MatMulMatM32(mat32[0],mat32[1],&mat32[2]); //matrix-matrix multiplication
printM32(mat32[2]); //printf the matrix

---

Last Updated : 2020/04/15
Modified By :

---

Details of update:
(2019/12/9)

1. Change the generation of invertible matrix to base on an initialized matrix (now just support for 8/32bits operations)
   
2. Unify the API
   
3. User can change the generation times in inverse.h
   
4. Use initinvbaseM(8/32)() function to generate an initialized invertible matrix and it's trails are recorded in basetrailM(8/32)
   8bits default value is 10
   32bits default value is 30
   which represent the operation times.
   
5. If not use the initialize function then each matrix generate from an identify matrix in defined times
   
6. New: copy function instead of identify function.
   

(2019/12/10)

1. Update 16/64/128bits inverse matrix function.
   New method has been covered.
   

(2019/12/11)

1. New: 16/64bit affine transformation.
   
2. New: 128bit affine transformation.
   No retrun value because of its special structure.

(2019/12/12)

1. New: 16/64/128bit affine combination operation.
   

(2019/12/16)

1. New: header files define code.
   

(2019/12/17)

1. Fix some errors.
   
2. New: Add parameter for initial base matrix function.
   The initial base matrix function has a max times and a min times for selection which is detailed in inverse.h .
   

(2020/01/08)

1. New: Add Matrix addition function.
   

(2020/01/10)

1. File tidying.
   
2. New: Add WBMatrix test.
   
3. New: Add Matrix Basis Method test.
   

(2020/01/12)

1. New: Add 128bit test for matrix basis method.
   

(2020/01/18)

1. Update test case: generate invertible matrix , compute inverse matrix.
   
2. Invertible: Matrix Basis Method, WBMatrix Method, Reverse Gaussian Elimination Method.
   
3. Inverse: WBMatrix Method, Matrix Basis Method.
   

(2020/01/20)

1. New: Add CMakeLists.txt
   
2. New: Add M4RI Method.
   

(2020/01/21)

1. Organize file structure, especially fix the structure.h and .c error.
   

(2020/01/22)

1. Delete xor.h.
   

(2020/01/30)

1. New: Add Gaussian elimination Method(Base on WBMatrix).
   
2. Change the generation function of random Matrix.
   

(2020/01/31)

1. New: Add Reverse LU Decomposition Method.
   

(2020/02/01)

1. Fixed: Function of random matrix.
   

(2020/02/02)

1. New: Comparison test on github.
   
2. New: Accuracy Test.
   
3. Fixed: Parameter Order of affinemix function.
   

(2020/02/07)

1. Fixed: Multipe define of global variables.
   
2. New: Function for random seed.
   
3. New: WBAES.
   

(2020/02/09)

1. Fixed: Poor randomness of random matrix function.
   
2. New: Function for estimate the invertibility of matrix.
   

(2020/02/16)

1. New: Add new test cases on github.
   

(2020/03/05)

1. New: Add performance test cases on M4RI: basic arithmetic with matrix .
   
2. New: Add performance test cases on NTL.
   
3. New: Add performance test cases on WBMatrix.
   

(2020/03/06)

1. New: Add vector addition.
   
2. Fixed: Accuracy test mode.
   
3. Optimized: Replace rotation with logical-AND.
   

(2020/03/07)

1. New: WBAES by M4RI.
   

(2020/03/09)

1. Update: WBMatrix Library for WBAES.
   

(2020/03/10)

1. New: WBSM4 by M4RI.
   
2. Fixed: the release version of WBAES(WBMatrix version).
   
3. New: WBSM4 by WBMatrix.
   

(2020/03/11)

1. New: WBSM4 by NTL.
   
2. Update: Clean-up NTL files.
   

(2020/03/15)

1. New: Release on github.
   

(2020/04/15)

1. New: support for returning Hamming Weight.
   
2. New: add an example for mitigating DCA attack.