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

###########################
README - ocf-linux-20100530
###########################

This README provides instructions for getting ocf-linux compiled and
operating in a generic linux environment.  Other information on the project
can be found at the home page:

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

Embedded systems and applications requiring userspace acceleration will need
to patch the kernel source to get full OCF support.  See "Adding OCF to
linux source" below.  Otherwise the "OCF Quickstart" that follows is the
easiest way to get started.

If your goal is to accelerate Openswan on Ubuntu or CentOS,  you may find
that the required binaries are already available on openswan.org:

    ftp://ftp.openswan.org/ocf/
    ftp://ftp.openswan.org/openswan/binaries/ubuntu/

#####################################################
OCF Quickstart for Ubuntu/Others (including Openswan)
#####################################################

This section provides instructions on how to quickly add kernel only support
for OCF to a GNU/Linux system.  It is only suitable for in-kernel use such as
Openswan MAST/KLIPS.

If the target is an embedded system, or, userspace acceleration of
applications such as OpenVPN and OpenSSL, the section below titled
"Adding OCF to linux source" is more appropriate.

Before building kernel only support for OCF ensure that the appropriate
linux-headers package is installed:

    cd ocf
    make ocf_modules
    sudo make ocf_install
    OCF_DIR=`pwd`            # remember where OCF sources were built

At this point the ocf, cryptosoft, ocfnull, hifn7751 and ocf-bench modules
should have been built and installed.  The OCF installation can be tested
with the following commands:

    modprobe ocf
    modprobe cryptosoft
    modprobe ocf-bench
    dmesg | tail -5

The final modprobe of ocf-bench will fail,  this is intentional as ocf-bench
is a short lived module that tests in-kernel performance of OCF.  If
everything worked correctly the "dmesg | tail -5" should include a line
like:

    [  583.128741] OCF: 45133 requests of 1488 bytes in 251 jiffies (535.122 Mbps)

This shows the in-kernel performance of OCF using the cryptosoft driver.
For addition driver load options,  see "How to load the OCF modules" below.

If the intention is to run an OCF accelerated Openswan (KLIPS/MAST) then use
these steps to compile openswan downloaded from openswan.org (2.6.34 or later).

    tar xf openswan-2.6.34.tar.gz
    cd openswan-2.6.34
    make programs
    make KERNELSRC=/lib/modules/`uname -r`/build \
        KBUILD_EXTRA_SYMBOLS=$OCF_DIR/Module.symvers \
        MODULE_DEF_INCLUDE=`pwd`/packaging/ocf/config-all.hmodules \
        MODULE_DEFCONFIG=`pwd`/packaging/ocf/defconfig \
        module
    sudo make KERNELSRC=/lib/modules/`uname -r`/build \
        KBUILD_EXTRA_SYMBOLS=$OCF_DIR/Module.symvers \
        MODULE_DEF_INCLUDE=`pwd`/packaging/ocf/config-all.hmodules \
        MODULE_DEFCONFIG=`pwd`/packaging/ocf/defconfig \
        install minstall

The rest of this document is only required for more complex build
requirements.

##########################
Adding OCF to linux source
##########################

It is recommended that OCF be built as modules as it increases the
flexibility and ease of debugging the system.

Ensure that the system has /dev/crypto for userspace access to OCF:

    mknod /dev/crypto c 10 70

Generate the kernel patches and apply the appropriate one.

    cd ocf
    make patch

This will provide three files:

    linux-2.4.*-ocf.patch
    linux-2.6.*-ocf.patch
    ocf-linux-base.patch

If either of the first two patches applies to the targets kernel,  then one
of the following as required:

    cd linux-2.X.Y; patch -p1 < linux-2.4.*-ocf.patch
    cd linux-2.6.Y; patch -p1 < linux-2.6.*-ocf.patch

Otherwise,  locate the appropriate kernel patch in the patches directory and
apply that as well as the ocf-linux-base.patch using '-p1'.

When using a linux-2.4 system on a non-x86 platform,  the following may be
required to build cryptosoft:

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

When using cryptosoft, for simplicity, enable all the crypto support in the
kernel except for the test driver.  Likewise for the OCF options.  Do not
enable OCF crypto drivers for HW that is not present (for example the ixp4xx
driver will not compile on non-Xscale systems).

Make sure that cryptodev.h from the ocf directory is installed as
crypto/cryptodev.h in an include directory that is used for building
applications for the target platform.  For example on a host system that
might be:

    /usr/include/crypto/cryptodev.h

Patch the openssl-0.9.8r code the openssl-0.9.8r.patch from the patches
directory.  There are many older patch versions in the patches directory
if required.

The openssl patches provide the following functionality:

    * 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 the crypto-tools directory for the target to obtain a userspace
testing tool call cryptotest.

###########################
How to load the OCF modules
###########################

First insert the base modules (cryptodev is optional,  it is only used
for userspace acceleration):

    modprobe ocf
    modprobe cryptodev

Load the software OCF driver with:

    modprobe cryptosoft

and zero or more of the OCF HW drivers with:

    modprobe safe
    modprobe hifn7751
    modprobe ixp4xx
    ...

All the drivers take a debug option to enable verbose debug so that
OCF operation may be observed via "dmesg" or the console.  For debug
load the modules as:

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

More than one OCF crypto driver may be loaded but then there is no
guarantee as to which will be used (other than a preference for HW
drivers over SW drivers by most applications).

It is also possible to enable debug at run time on linux-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
    ...

The ocf-bench driver accepts the following parameters:

    request_q_len - Maximum number of outstanding requests to OCF
    request_num   - run for at least this many requests
    request_size  - size of each request (multiple of 16 bytes recommended)
    request_batch - enable OCF request batching
    request_cbimm - enable OCF immediate callback on completion

For example:

    modprobe ocf-bench request_size=1024 request_cbimm=0

#######################
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
#
#############################