README - ocf-linux-20100325
---------------------------

This README provides instructions for getting ocf-linux compiled and
operating in a generic linux environment.  For other information you
might like to visit the home page for this project:

    http://ocf-linux.sourceforge.net/

Adding OCF to linux
-------------------

    Not much in this file for now,  just some notes.  I usually build
    the ocf support as modules but it can be built into the kernel as
    well.  To use it:

    * mknod /dev/crypto c 10 70

    * to add OCF to your kernel source,  you have two options.  Apply
      the kernel specific patch:

          cd linux-2.4*; gunzip < ocf-linux-24-XXXXXXXX.patch.gz | patch -p1
          cd linux-2.6*; gunzip < ocf-linux-26-XXXXXXXX.patch.gz | patch -p1
    
      if you do one of the above,  then you can proceed to the next step,
      or you can do the above process by hand with using the patches against
      linux-2.4.35 and 2.6.33 to include the ocf code under crypto/ocf.
      Here's how to add it:

      for 2.4.35 (and later)

          cd linux-2.4.35/crypto
          tar xvzf ocf-linux.tar.gz
          cd ..
          patch -p1 < crypto/ocf/patches/linux-2.4.35-ocf.patch

      for 2.6.23 (and later),  find the kernel patch specific (or nearest)
      to your kernel versions and then:

          cd linux-2.6.NN/crypto
          tar xvzf ocf-linux.tar.gz
          cd ..
          patch -p1 < crypto/ocf/patches/linux-2.6.NN-ocf.patch

      It should be easy to take this patch and apply it to other more
      recent versions of the kernels.  The same patches should also work
      relatively easily on kernels as old as 2.6.11 and 2.4.18.
      
    * under 2.4 if you are on a non-x86 platform,  you may need to:

        cp linux-2.X.x/include/asm-i386/kmap_types.h linux-2.X.x/include/asm-YYY

      so that you can build the kernel crypto support needed for the cryptosoft
      driver.

    * For simplicity you should enable all the crypto support in your kernel
      except for the test driver.  Likewise for the OCF options.  Do not
      enable OCF crypto drivers for HW that you do not have (for example
      ixp4xx will not compile on non-Xscale systems).

    * make sure that cryptodev.h (from ocf-linux.tar.gz) is installed as
      crypto/cryptodev.h in an include directory that is used for building
      applications for your platform.  For example on a host system that
      might be:

              /usr/include/crypto/cryptodev.h

    * patch your openssl-0.9.8n code with the openssl-0.9.8n.patch.
      (NOTE: there is no longer a need to patch ssh). The patch is against:
      openssl-0_9_8e

      If you need a patch for an older version of openssl,  you should look
      to older OCF releases.  This patch is unlikely to work on older
      openssl versions.

      openssl-0.9.8n.patch
                - enables --with-cryptodev for non BSD systems
                - adds -cpu option to openssl speed for calculating CPU load
                  under linux
                - fixes null pointer in openssl speed multi thread output.
                - fixes test keys to work with linux crypto's more stringent
                  key checking.
                - adds MD5/SHA acceleration (Ronen Shitrit), only enabled
                  with the --with-cryptodev-digests option
                - fixes bug in engine code caching.

    * build crypto-tools-XXXXXXXX.tar.gz if you want to try some of the BSD
      tools for testing OCF (ie., cryptotest).

How to load the OCF drivers
---------------------------

    First insert the base modules:

        insmod ocf
        insmod cryptodev

    You can then install the software OCF driver with:

        insmod cryptosoft

    and one or more of the OCF HW drivers with:

        insmod safe
        insmod hifn7751
        insmod ixp4xx
        ...

    all the drivers take a debug option to enable verbose debug so that
    you can see what is going on.  For debug you load them as:

        insmod ocf crypto_debug=1
        insmod cryptodev cryptodev_debug=1
        insmod cryptosoft swcr_debug=1

    You may load more than one OCF crypto driver but then there is no guarantee
    as to which will be used.

    You can also enable debug at run time on 2.6 systems with the following:

        echo 1 > /sys/module/ocf/parameters/crypto_debug
        echo 1 > /sys/module/cryptodev/parameters/cryptodev_debug
        echo 1 > /sys/module/cryptosoft/parameters/swcr_debug
        echo 1 > /sys/module/hifn7751/parameters/hifn_debug
        echo 1 > /sys/module/safe/parameters/safe_debug
        echo 1 > /sys/module/ixp4xx/parameters/ixp_debug
        ...

Testing the OCF support
-----------------------

    run "cryptotest",  it should do a short test for a couple of
    des packets.  If it does everything is working.

    If this works,  then ssh will use the driver when invoked as:

        ssh -c 3des username@host

    to see for sure that it is operating, enable debug as defined above.

    To get a better idea of performance run:

        cryptotest 100 4096

    There are more options to cryptotest,  see the help.

    It is also possible to use openssl to test the speed of the crypto
    drivers.

        openssl speed -evp des -engine cryptodev -elapsed
        openssl speed -evp des3 -engine cryptodev -elapsed
        openssl speed -evp aes128 -engine cryptodev -elapsed

    and multiple threads (10) with:

        openssl speed -evp des -engine cryptodev -elapsed -multi 10
        openssl speed -evp des3 -engine cryptodev -elapsed -multi 10
        openssl speed -evp aes128 -engine cryptodev -elapsed -multi 10

    for public key testing you can try:

        cryptokeytest
        openssl speed -engine cryptodev rsa -elapsed
        openssl speed -engine cryptodev dsa -elapsed

David McCullough
david_mccullough@mcafee.com