Documentation/s390/crypto/crypto-API.txt

   1 crypto-API support for z990 Message Security Assist (MSA) instructions
   2 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   3
   4 AUTHOR: Thomas Spatzier (tspat@de.ibm.com)
   5
   6
   7 1. Introduction crypto-API
   8 ~~~~~~~~~~~~~~~~~~~~~~~~~~
   9 See Documentation/crypto/api-intro.txt for an introduction/description of the
  10 kernel crypto API.
  11 According to api-intro.txt support for z990 crypto instructions has been added
  12 in the algorithm api layer of the crypto API. Several files containing z990
  13 optimized implementations of crypto algorithms are placed in the
  14 arch/s390/crypto directory.
  15
  16
  17 2. Probing for availability of MSA
  18 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  19 It should be possible to use Kernels with the z990 crypto implementations both
  20 on machines with MSA available and on those without MSA (pre z990 or z990
  21 without MSA). Therefore a simple probing mechanism has been implemented:
  22 In the init function of each crypto module the availability of MSA and of the
  23 respective crypto algorithm in particular will be tested. If the algorithm is
  24 available the module will load and register its algorithm with the crypto API.
  25
  26 If the respective crypto algorithm is not available, the init function will
  27 return -ENOSYS. In that case a fallback to the standard software implementation
  28 of the crypto algorithm must be taken ( -> the standard crypto modules are
  29 also built when compiling the kernel).
  30
  31
  32 3. Ensuring z990 crypto module preference
  33 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  34 If z990 crypto instructions are available the optimized modules should be
  35 preferred instead of standard modules.
  36
  37 3.1. compiled-in modules
  38 ~~~~~~~~~~~~~~~~~~~~~~~~
  39 For compiled-in modules it has to be ensured that the z990 modules are linked
  40 before the standard crypto modules. Then, on system startup the init functions
  41 of z990 crypto modules will be called first and query for availability of z990
  42 crypto instructions. If instruction is available, the z990 module will register
  43 its crypto algorithm implementation -> the load of the standard module will fail
  44 since the algorithm is already registered.
  45 If z990 crypto instruction is not available the load of the z990 module will
  46 fail -> the standard module will load and register its algorithm.
  47
  48 3.2. dynamic modules
  49 ~~~~~~~~~~~~~~~~~~~~
  50 A system administrator has to take care of giving preference to z990 crypto
  51 modules. If MSA is available appropriate lines have to be added to
  52 /etc/modprobe.conf.
  53
  54 Example:        z990 crypto instruction for SHA1 algorithm is available
  55
  56                 add the following line to /etc/modprobe.conf (assuming the
  57                 z990 crypto modules for SHA1 is called sha1_z990):
  58
  59                 alias sha1 sha1_z990
  60
  61                 -> when the sha1 algorithm is requested through the crypto API
  62                 (which has a module autoloader) the z990 module will be loaded.
  63
  64 TBD:    a userspace module probing mechanism
  65         something like 'probe sha1 sha1_z990 sha1' in modprobe.conf
  66         -> try module sha1_z990, if it fails to load standard module sha1
  67         the 'probe' statement is currently not supported in modprobe.conf
  68
  69
  70 4. Currently implemented z990 crypto algorithms
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  72 The following crypto algorithms with z990 MSA support are currently implemented.
  73 The name of each algorithm under which it is registered in crypto API and the
  74 name of the respective module is given in square brackets.
  75
  76 - SHA1 Digest Algorithm [sha1 -> sha1_z990]
  77 - DES Encrypt/Decrypt Algorithm (64bit key) [des -> des_z990]
  78 - Triple DES Encrypt/Decrypt Algorithm (128bit key) [des3_ede128 -> des_z990]
  79 - Triple DES Encrypt/Decrypt Algorithm (192bit key) [des3_ede -> des_z990]
  80
  81 In order to load, for example, the sha1_z990 module when the sha1 algorithm is
  82 requested (see 3.2.) add 'alias sha1 sha1_z990' to /etc/modprobe.conf.
  83