diff options
Diffstat (limited to 'Documentation/s390/crypto/crypto-API.txt')
| -rw-r--r-- | Documentation/s390/crypto/crypto-API.txt | 83 |
1 files changed, 0 insertions, 83 deletions
diff --git a/Documentation/s390/crypto/crypto-API.txt b/Documentation/s390/crypto/crypto-API.txt deleted file mode 100644 index 71ae6ca9f2c2..000000000000 --- a/Documentation/s390/crypto/crypto-API.txt +++ /dev/null | |||
| @@ -1,83 +0,0 @@ | |||
| 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 | |||