1 files changed, 83 insertions, 0 deletions

diff --git a/Documentation/s390/crypto/crypto-API.txt b/Documentation/s390/crypto/crypto-API.txt
new file mode 100644
index 000000000000..78a77624a716
--- /dev/null
+++ b/Documentation/s390/crypto/crypto-API.txt
@@ -0,0 +1,83 @@
+crypto-API support for z990 Message Security Assist (MSA) instructions
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+AUTHOR: Thomas Spatzier (tspat@de.ibm.com)
+
+
+1. Introduction crypto-API
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+See Documentation/crypto/api-intro.txt for an introduction/description of the
+kernel crypto API.
+According to api-intro.txt support for z990 crypto instructions has been added
+in the algorithm api layer of the crypto API. Several files containing z990
+optimized implementations of crypto algorithms are placed in the
+arch/s390/crypto directory.
+
+
+2. Probing for availability of MSA
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+It should be possible to use Kernels with the z990 crypto implementations both
+on machines with MSA available an on those without MSA (pre z990 or z990
+without MSA). Therefore a simple probing mechanisms has been implemented:
+In the init function of each crypto module the availability of MSA and of the
+respective crypto algorithm in particular will be tested. If the algorithm is
+available the module will load and register its algorithm with the crypto API.
+
+If the respective crypto algorithm is not available, the init function will
+return -ENOSYS. In that case a fallback to the standard software implementation
+of the crypto algorithm must be taken ( -> the standard crypto modules are
+also build when compiling the kernel).
+
+
+3. Ensuring z990 crypto module preference
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If z990 crypto instructions are available the optimized modules should be
+preferred instead of standard modules.
+
+3.1. compiled-in modules
+~~~~~~~~~~~~~~~~~~~~~~~~
+For compiled-in modules it has to be ensured that the z990 modules are linked
+before the standard crypto modules. Then, on system startup the init functions
+of z990 crypto modules will be called first and query for availability of z990
+crypto instructions. If instruction is available, the z990 module will register
+its crypto algorithm implementation -> the load of the standard module will fail
+since the algorithm is already registered.
+If z990 crypto instruction is not available the load of the z990 module will
+fail -> the standard module will load and register its algorithm.
+
+3.2. dynamic modules
+~~~~~~~~~~~~~~~~~~~~
+A system administrator has to take care of giving preference to z990 crypto
+modules. If MSA is available appropriate lines have to be added to
+/etc/modprobe.conf.
+
+Example:        z990 crypto instruction for SHA1 algorithm is available
+
+                add the following line to /etc/modprobe.conf (assuming the
+                z990 crypto modules for SHA1 is called sha1_z990):
+
+                alias sha1 sha1_z990
+
+                -> when the sha1 algorithm is requested through the crypto API
+                (which has a module autoloader) the z990 module will be loaded.
+
+TBD:    a userspace module probin mechanism
+        something like 'probe sha1 sha1_z990 sha1' in modprobe.conf
+        -> try module sha1_z990, if it fails to load load standard module sha1
+        the 'probe' statement is currently not supported in modprobe.conf
+
+
+4. Currently implemented z990 crypto algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following crypto algorithms with z990 MSA support are currently implemented.
+The name of each algorithm under which it is registered in crypto API and the
+name of the respective module is given in square brackets.
+
+- SHA1 Digest Algorithm [sha1 -> sha1_z990]
+- DES Encrypt/Decrypt Algorithm (64bit key) [des -> des_z990]
+- Tripple DES Encrypt/Decrypt Algorithm (128bit key) [des3_ede128 -> des_z990]
+- Tripple DES Encrypt/Decrypt Algorithm (192bit key) [des3_ede -> des_z990]
+
+In order to load, for example, the sha1_z990 module when the sha1 algorithm is
+requested (see 3.2.) add 'alias sha1 sha1_z990' to /etc/modprobe.conf.
+