########################### README - ocf-linux-20120127 ########################### 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 four files: linux-2.4.*-ocf.patch linux-2.6.*-ocf.patch linux-3.*-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 cd linux-3.Y; patch -p1 < linux-3.*-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 # #############################