target/linux/generic/files/crypto/ocf/README

   1 README - ocf-linux-20100325
   2 ---------------------------
   3
   4 This README provides instructions for getting ocf-linux compiled and
   5 operating in a generic linux environment.  For other information you
   6 might like to visit the home page for this project:
   7
   8     http://ocf-linux.sourceforge.net/
   9
  10 Adding OCF to linux
  11 -------------------
  12
  13     Not much in this file for now,  just some notes.  I usually build
  14     the ocf support as modules but it can be built into the kernel as
  15     well.  To use it:
  16
  17     * mknod /dev/crypto c 10 70
  18
  19     * to add OCF to your kernel source,  you have two options.  Apply
  20       the kernel specific patch:
  21
  22           cd linux-2.4*; gunzip < ocf-linux-24-XXXXXXXX.patch.gz | patch -p1
  23           cd linux-2.6*; gunzip < ocf-linux-26-XXXXXXXX.patch.gz | patch -p1
  24
  25       if you do one of the above,  then you can proceed to the next step,
  26       or you can do the above process by hand with using the patches against
  27       linux-2.4.35 and 2.6.33 to include the ocf code under crypto/ocf.
  28       Here's how to add it:
  29
  30       for 2.4.35 (and later)
  31
  32           cd linux-2.4.35/crypto
  33           tar xvzf ocf-linux.tar.gz
  34           cd ..
  35           patch -p1 < crypto/ocf/patches/linux-2.4.35-ocf.patch
  36
  37       for 2.6.23 (and later),  find the kernel patch specific (or nearest)
  38       to your kernel versions and then:
  39
  40           cd linux-2.6.NN/crypto
  41           tar xvzf ocf-linux.tar.gz
  42           cd ..
  43           patch -p1 < crypto/ocf/patches/linux-2.6.NN-ocf.patch
  44
  45       It should be easy to take this patch and apply it to other more
  46       recent versions of the kernels.  The same patches should also work
  47       relatively easily on kernels as old as 2.6.11 and 2.4.18.
  48
  49     * under 2.4 if you are on a non-x86 platform,  you may need to:
  50
  51         cp linux-2.X.x/include/asm-i386/kmap_types.h linux-2.X.x/include/asm-YYY
  52
  53       so that you can build the kernel crypto support needed for the cryptosoft
  54       driver.
  55
  56     * For simplicity you should enable all the crypto support in your kernel
  57       except for the test driver.  Likewise for the OCF options.  Do not
  58       enable OCF crypto drivers for HW that you do not have (for example
  59       ixp4xx will not compile on non-Xscale systems).
  60
  61     * make sure that cryptodev.h (from ocf-linux.tar.gz) is installed as
  62       crypto/cryptodev.h in an include directory that is used for building
  63       applications for your platform.  For example on a host system that
  64       might be:
  65
  66               /usr/include/crypto/cryptodev.h
  67
  68     * patch your openssl-0.9.8n code with the openssl-0.9.8n.patch.
  69       (NOTE: there is no longer a need to patch ssh). The patch is against:
  70       openssl-0_9_8e
  71
  72       If you need a patch for an older version of openssl,  you should look
  73       to older OCF releases.  This patch is unlikely to work on older
  74       openssl versions.
  75
  76       openssl-0.9.8n.patch
  77                 - enables --with-cryptodev for non BSD systems
  78                 - adds -cpu option to openssl speed for calculating CPU load
  79                   under linux
  80                 - fixes null pointer in openssl speed multi thread output.
  81                 - fixes test keys to work with linux crypto's more stringent
  82                   key checking.
  83                 - adds MD5/SHA acceleration (Ronen Shitrit), only enabled
  84                   with the --with-cryptodev-digests option
  85                 - fixes bug in engine code caching.
  86
  87     * build crypto-tools-XXXXXXXX.tar.gz if you want to try some of the BSD
  88       tools for testing OCF (ie., cryptotest).
  89
  90 How to load the OCF drivers
  91 ---------------------------
  92
  93     First insert the base modules:
  94
  95         insmod ocf
  96         insmod cryptodev
  97
  98     You can then install the software OCF driver with:
  99
 100         insmod cryptosoft
 101
 102     and one or more of the OCF HW drivers with:
 103
 104         insmod safe
 105         insmod hifn7751
 106         insmod ixp4xx
 107         ...
 108
 109     all the drivers take a debug option to enable verbose debug so that
 110     you can see what is going on.  For debug you load them as:
 111
 112         insmod ocf crypto_debug=1
 113         insmod cryptodev cryptodev_debug=1
 114         insmod cryptosoft swcr_debug=1
 115
 116     You may load more than one OCF crypto driver but then there is no guarantee
 117     as to which will be used.
 118
 119     You can also enable debug at run time on 2.6 systems with the following:
 120
 121         echo 1 > /sys/module/ocf/parameters/crypto_debug
 122         echo 1 > /sys/module/cryptodev/parameters/cryptodev_debug
 123         echo 1 > /sys/module/cryptosoft/parameters/swcr_debug
 124         echo 1 > /sys/module/hifn7751/parameters/hifn_debug
 125         echo 1 > /sys/module/safe/parameters/safe_debug
 126         echo 1 > /sys/module/ixp4xx/parameters/ixp_debug
 127         ...
 128
 129 Testing the OCF support
 130 -----------------------
 131
 132     run "cryptotest",  it should do a short test for a couple of
 133     des packets.  If it does everything is working.
 134
 135     If this works,  then ssh will use the driver when invoked as:
 136
 137         ssh -c 3des username@host
 138
 139     to see for sure that it is operating, enable debug as defined above.
 140
 141     To get a better idea of performance run:
 142
 143         cryptotest 100 4096
 144
 145     There are more options to cryptotest,  see the help.
 146
 147     It is also possible to use openssl to test the speed of the crypto
 148     drivers.
 149
 150         openssl speed -evp des -engine cryptodev -elapsed
 151         openssl speed -evp des3 -engine cryptodev -elapsed
 152         openssl speed -evp aes128 -engine cryptodev -elapsed
 153
 154     and multiple threads (10) with:
 155
 156         openssl speed -evp des -engine cryptodev -elapsed -multi 10
 157         openssl speed -evp des3 -engine cryptodev -elapsed -multi 10
 158         openssl speed -evp aes128 -engine cryptodev -elapsed -multi 10
 159
 160     for public key testing you can try:
 161
 162         cryptokeytest
 163         openssl speed -engine cryptodev rsa -elapsed
 164         openssl speed -engine cryptodev dsa -elapsed
 165
 166 David McCullough
 167 david_mccullough@mcafee.com