TargetImpKernel

Overview

• The KERNEL environment variable specifies the target implementation type:

  KERNEL	KERNEL_NAMEOF	KERNEL_MODEOF	Description	user	fvr_k	fvr_d	svr_d	rvr_d
  aead	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_DEFAULT	A generic AEAD cipher, in encryption mode (which is encryption)	o
  aead	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_ENC	A generic AEAD cipher, in encryption mode	o
  aead	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_DEC	A generic AEAD cipher, in decryption mode	o
  block	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_DEFAULT	A generic block cipher, in default mode (which is encryption)	o	o	o		o
  block	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_ENC	A generic block cipher, in encryption mode	o	o	o		o
  block	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_DEC	A generic block cipher, in decryption mode	o	o	o		o
  block	KERNEL_NAMEOF_AES	KERNEL_MODEOF_DEFAULT	The AES block cipher, in encryption mode (which is encryption)	o	o	o	o	o
  block	KERNEL_NAMEOF_AES	KERNEL_MODEOF_ENC	The AES block cipher, in encryption mode	o	o	o	o	o
  block	KERNEL_NAMEOF_AES	KERNEL_MODEOF_DEC	The AES block cipher, in decryption mode	o	o	o	o	o
  function	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_DEFAULT	A generic function, i.e., some f which, given x, computes r = f( x ), in default mode	o
  hash	KERNEL_NAMEOF_GENERIC	KERNEL_MODEOF_DEFAULT	A generic hash function, in default mode	o
  hash	KERNEL_NAMEOF_SHA_1	KERNEL_MODEOF_DEFAULT	The SHA-1 hash function, in default mode	o
  hash	KERNEL_NAMEOF_SHA_2_224	KERNEL_MODEOF_DEFAULT	The SHA-224 hash function, in default mode	o
  hash	KERNEL_NAMEOF_SHA_2_256	KERNEL_MODEOF_DEFAULT	The SHA-256 hash function, in default mode	o
  hash	KERNEL_NAMEOF_SHA_2_384	KERNEL_MODEOF_DEFAULT	The SHA-384 hash function, in default mode	o
  hash	KERNEL_NAMEOF_SHA_2_512	KERNEL_MODEOF_DEFAULT	The SHA-512 hash function, in default mode	o

  • where

    • the far left-hand 3 columns capture the kernel configuration,
    • the far right-hand 5 columns capture the supported driver policies, by which the back-end interacts with the kernel: either user for user-controller, or, e.g., fvr_d for TVLA-based fixed-versus-random.

    The latter also dictates whether a given kernel configuration can be supported by automated processes such as CI.

• In theory, each kernel is structured so realising the target implementation is a matter of editing

  1. the implementation itself in

     ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h
     ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c

  2. the manifest in

     ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.manifest

     to specify any additional files that supplement and thus support the implementation.

  Note, for example, that

  ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h_harness
  ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c_harness

  are part of the provided harness and should remain unchanged.
  In practice, doing so is somewhat kernel-specific: more detail is captured within the sub-sections below.

Kernel-specific detail: aead

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_NAMEOF and KERNEL_MODEOF to specify a configuration per the table above. For example,

  #define KERNEL_NAMEOF KERNEL_NAMEOF_GENERIC
  #define KERNEL_MODEOF KERNEL_MODEOF_ENC

  specifies a generic AEAD cipher in encryption mode.

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_SIZEOF_ESR, KERNEL_SIZEOF_K, KERNEL_SIZEOF_A, KERNEL_SIZEOF_N, KERNEL_SIZEOF_M, and KERNEL_SIZEOF_C to specify the allocated (i.e., maximum) size of associated registers. For example,

  #define KERNEL_SIZEOF_ESR  0
  #define KERNEL_SIZEOF_K   16
  #define KERNEL_SIZEOF_A   16
  #define KERNEL_SIZEOF_N   16
  #define KERNEL_SIZEOF_M   16
  #define KERNEL_SIZEOF_C   16

  specifies a 0-byte esr register (for externally supplied randomness), upto a 16-byte k register (for the cipher key), upto a 16-byte n register (for the nonce), upto a 16-byte a register (for the associated data), upto a 16-byte m register (for the plaintext data), and upto a 16-byte c register (for the ciphertext data).

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c, complete the kernel function (and optionally kernel_prologue and kernel_epilogue) to realise the target implementation.

Kernel-specific detail: block

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_NAMEOF and KERNEL_MODEOF to specify a configuration per the table above. For example,

  #define KERNEL_NAMEOF KERNEL_NAMEOF_AES
  #define KERNEL_MODEOF KERNEL_MODEOF_DEC

  specifies the AES block cipher in decryption mode.

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_SIZEOF_ESR, KERNEL_SIZEOF_K, KERNEL_SIZEOF_M, and KERNEL_SIZEOF_C to specify the allocated (i.e., maximum) size of associated registers. For example,

  #define KERNEL_SIZEOF_ESR  8
  #define KERNEL_SIZEOF_K   16
  #define KERNEL_SIZEOF_M   16
  #define KERNEL_SIZEOF_C   16

  specifies upto an 8-byte esr register (for externally supplied randomness), upto a 16-byte k register (for the cipher key), upto a 16-byte m register (for the plaintext data), and upto a 16-byte c register (for the ciphertext data).

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c, complete the kernel function (and optionally kernel_prologue and kernel_epilogue) to realise the target implementation.

Kernel-specific detail: function

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_NAMEOF and KERNEL_MODEOF to specify a configuration per the table above. For example,

  #define KERNEL_NAMEOF KERNEL_NAMEOF_GENERIC
  #define KERNEL_MODEOF KERNEL_MODEOF_DEFAULT

  specifies a generic function in the default mode.

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_ELEMOF_X and KERNEL_ELEMOF_R to specify the number of input and output registers. For example,

  #define KERNEL_ELEMOF_X 2
  #define KERNEL_ELEMOF_R 1

  specifies 2 input registers (namely x0 and x1), and 1 output register (namely r0).

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_TYPEOF_X0, KERNEL_TYPEOF_X1, etc., and KERNEL_TYPEOF_R0, etc., to specify the type of associated registers. This is achieved by combining together individual tokens, e.g.,

  • KERNEL_DATA_TYPE_I represents an input register,
  • KERNEL_DATA_TYPE_O represents an output register,
  • KERNEL_DATA_TYPE_S represents a variable-size register, and
  • KERNEL_DATA_TYPE_V represents a security-critical register,

  with CONS to form a type identifier. For example

  #define KERNEL_TYPEOF_X0 KERNEL_DATA_TYPE_I

  specifies that x0 is an input register,

  #define KERNEL_TYPEOF_X1 CONS(KERNEL_DATA_TYPE_I,KERNEL_DATA_TYPE_S)

  specifies that x1 is a security-critical input register,

  #define KERNEL_TYPEOF_R0 CONS(CONS(KERNEL_DATA_TYPE_O,KERNEL_DATA_TYPE_S),KERNEL_DATA_TYPE_V)

  specifies that r0 is a security-critical, variable-size output register.

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_SIZEOF_ESR, KERNEL_SIZEOF_X, and KERNEL_SIZEOF_R to specify the allocated (i.e., maximum) size of associated registers. For example

  #define KERNEL_SIZEOF_ESR 16
  #define KERNEL_SIZEOF_X   32
  #define KERNEL_SIZEOF_R   32

  specifies upto an 16-byte esr register (for externally supplied randomness), upto a 32-byte x0 register (for the input data), upto a 32-byte x1 register (for the input data), and upto a 32-byte r0 register (for the output data).

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c, complete the kernel function (and optionally kernel_prologue and kernel_epilogue) to realise the target implementation.

Kernel-specific detail: hash

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_NAMEOF and KERNEL_MODEOF to specify a configuration per the table above. For example,

  #define KERNEL_NAMEOF KERNEL_NAMEOF_SHA_1
  #define KERNEL_MODEOF KERNEL_MODEOF_DEFAULT

  specifies the SHA-1 hash function in the default mode.

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.h, define KERNEL_SIZEOF_ESR, KERNEL_SIZEOF_M, and KERNEL_SIZEOF_D to specify the allocated (i.e., maximum) size of associated registers. For example,

  #define KERNEL_SIZEOF_ESR  0
  #define KERNEL_SIZEOF_M   64
  #define KERNEL_SIZEOF_D   20

  specifies an 0-byte esr register (for externally supplied randomness), upto a 64-byte m register (for the message data), and upto a 20-byte d register (for the digest data).

• In ${REPO_HOME}/src/sca3s/harness/kernel/${KERNEL}/kernel_imp.c, complete the kernel function (and optionally kernel_prologue and kernel_epilogue) to realise the target implementation.