Pykrete Whitebox

Implementation of AES whitebox schemes Chow and Karroumi (both one dual per round and one dual per row per round) in pure Rust.

CLI Usage

This repo provides a pykrete-mkvm CLI, which allows to generate whitebox AES code for multiple languages

Usage: pykrete-mkvm <COMMAND>

Commands:
  create-external-encoding  Create external encoding
  expand-round-keys         Expand aes key into round keys
  create-round-keys         Create round keys directly
  create-whitebox           Generate AES whitebox code

create-external-encoding

Create external encoding.

Applying those will make the output incompatible with standard AES, but it makes it much harder to extract the original encryption keys (given that no one has access to the external encodings).

Usage: pykrete-mkvm create-external-encoding --out <OUT>

Options:
      --out <OUT>
          Output file

expand-round-keys

Expand AES key into round keys.

First round key is equal to the specified key, other round keys are derived from it in a predictable way.

Usage: pykrete-mkvm expand-round-keys --out <OUT> <T> <KEY>

Arguments:
  <T>
          AES standard size

          [possible values: aes128, aes192, aes256]

  <KEY>
          AES key: 16 bytes

Options:
      --out <OUT>
          Output file

create-round-keys

Create round keys directly.

Little bit more secure for white-box context, as it makes it impossible to use knowledge of ExpandKeys algorithm to get the original key from one of the round keys.

Usage: pykrete-mkvm create-round-keys --out <OUT> <T>

Arguments:
  <T>
          AES standard size

          [possible values: aes128, aes192, aes256]

Options:
      --out <OUT>
          Output file

create-whitebox

Generate AES whitebox code.

Usage: pykrete-mkvm create-whitebox [OPTIONS] --key <KEY> --language <LANGUAGE> <T>

Arguments:
  <T>
          AES standard size

          [possible values: aes128, aes192, aes256]

Options:
      --key <KEY>
          Expanded key file - can be created using expand-round-keys or create-round-keys

      --input-encoding <INPUT_ENCODING>
          Apply external encoding on the input, external encoding can be created using `create-external-encoding` subcommand

          The result will not be compatible with standard AES, you would need server side support for encrypting/decrypting the input/output.

          If prefixed with ! - the inverse of the encoding is applied

      --output-encoding <OUTPUT_ENCODING>
          Apply external encoding on the output, external encoding can be created using `create-external-encoding` subcommand

          The result will not be compatible with standard AES, you would need server side support for encrypting/decrypting the input/output.

          If prefixed with ! - the inverse of the encoding is applied

      --inv
          If not set - AES is performing the encryption operation, otherwise - decryption

      --language <LANGUAGE>
          For which language the whitebox code should be generated

          Possible values:
          - js
          - python
          - rust
          - java

      --debug
          Pretty-print output

      --no-reorder
          Do not reorder VM instructions

      --no-mb
          Do not use mixing bijections, reduces the attack complexity

          Disabling both MB and L reduces code size in half

      --no-l
          Do not use mixing bijections, reduces the attack complexity

          Disabling both MB and L reduces code size in half

      --no-internal-encodings
          Do not use mixing bijections, reduces the attack complexity

          Greately reduces the code size

      --karroumi <KARROUMI>
          Use Karroumi whitebox scheme instead of plain Chow

          Greately increases VM generation time

          Possible values:
          - per-round: Each round uses a different AES dual, slow
          - per-row:   Each row in each round uses a different AES dual, very slow

      --aes-dual <AES_DUAL>
          Generate an AES using non-standard affine transform, MixColumns and SBox are affected

          The result will not be compatible with standard AES, you would need server side support for encrypting/decrypting the input/output.

          Accepts a single integer 0-240 for the given AES dual cipher, defaults to zero for standard AES

          [default: 0]

Performance

Similar to other whitebox aes implementations during runtime, but the compiler is very slow.

I have not used any library for matrix math (because there I have found no good GF2 math libraries for Rust), many calculations (especially matrix inversions) are performed on the spot instead of caching them/passing them around, and because of that this project is pretty CPU hungry, especially for Karroumi impl, as it compuates sbox multiple times for every single round.

Security

What security?

Do not use this if you don’t know what are you doing. Better - do not use this at all other than for learning purposes.

Not included in this repo many improvements over karroumi scheme, more security measures, and analyzer that is able to reverse the VM code (as generated by published mkvm codegenerator) using DFA, meaning you can consider this implementation as compromised as every other whitebox aes implementation.

There is multiple ways this implementation might be improved, but I only want this repo to be AES/Rjindael adjacement with the algorighms primarily based on academic papers.

License

GPLv3 with me (Lach) solely holding the copyright. I have a proprietary version of the same codebase with private modification that is being used for some other tasks.

Credits

Dušan Klinec: White-box attack resistant cryptography.

Stanley Chow, Phil Eisen, Harold Johnson, and Paul C. Van Oorschot: White-box cryptography and an AES implementation.

Mohamed Karroumi: Protecting white-box AES with dual ciphers.