Readme for the MontaVista* Linux* 3.1 OpenSSL*/OCF and
Intel® IXP400 Software v1.4 Integration
=========================================================================
Introduction:
=============
OCF - OpenBSD Cryptographic Framework
NOTE: These instructions are provided in addition to the readme that accompanies
the ocf-linux-20041202 release distributed on SourceForge*.
This readme is intended to assist those that want to use OpenSSL/OCF with Intel® IXP400
Software and integrate with MontaVista* Linux* Professional Edition 3.1
(MVL3.1) IXDP425 Linux Support Package (IXDP425 LSP).
Notices
=======
INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL® PRODUCTS
EXCEPT AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH
PRODUCTS, INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY
EXPRESS OR IMPLIED WARRANTY RELATING TO SALE AND/OR USE OF INTEL PRODUCTS,
INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR
PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT, OR
OTHER INTELLECTUAL PROPERTY RIGHT. Intel products are not intended for use
in medical, life saving, life sustaining, critical control or safety systems,
or in nuclear facility applications.
Intel may make changes to the Software, or to items referenced therein, at any time without
notice, but is not obligated to support, update or provide training for the Software.
Intel Corporation may have patents or pending patent applications, trademarks,
copyrights, or other intellectual property rights that relate to the presented subject
matter. The furnishing of documents and other materials and information does not provide any
license, express or implied, by estoppel or otherwise, to any such patents, trademarks,
copyrights, or other intellectual property rights.
Copyright © 2005, Intel Corporation. All Rights Reserved.
*Other names and brands may be claimed as the property of others.
Revision history
================
1.0 - initial release, 2/6/2005
-------------------------------------------------------------------------
Integration Steps
=================
1. Prerequisites
2. Set up and verify the baseline MVL3.1 kernel with Intel® IXP400
Software v1.4
3. Enable the Crypto support in the Ethernet device driver
4. Integrate OCF support
- un-tar the OCF-linux source files
- Modify the Linux include miscdevice.h
- Set up the kernel configuration
- Update the MVL3.1 Crypto support
- Un-tar the OCF Crypto driver
. Edit the kernel drivers Makefile
. Edit the drivers/ocf/makefile
5. Configure and build the Kernel
6. Set up the Crypto device driver node
7. Set up OpenSSL
- Get the source
- Extract and patch
- Configure and Build
- Basic Install
- Verify operation
8. Resources, links and Q/A
1. Prerequisites
================
- These instructions are written to accommodate most Linux developers,
but a high level of Linux kernel/driver experience is required to further
modify this driver/system. These instructions should be easy to
follow, but additional familiarity with the kernel
may be required to apply patches and troubleshoot.
- MontaVista Linux Professional Edition 3.1 (MVL3.1) LSP
Obtain and install the update for the Intel Corporation IXDP425 / IXCDP1100
Development Platform (Big-Endian) BE. Use LSP release 0400824.29
http://support.mvista.com
- Obtain the Intel® IXP400 Software v1.4 with Crypto support
http://www.intel.com/design/network/products/npfamily/ixp425swr1.htm
- Obtain the Intel® IXP400 Software Linux Ethernet Device Driver v1.1
http://www.intel.com/design/network/products/npfamily/ixp400_osc.htm
- Obtain the Intel® IXP400 Software IPSec VPN Example code: Based
on FreeS/WAN* 1.99, verified with Intel® IXP400 Software Release v1.4
and MontaVista Linux 3.0.
http://www.intel.com/design/network/products/npfamily/ixp400_osc.htm
- Obtain the OCF Driver with IXP400 software integration source tar file.
http://prdownloads.sourceforge.net/ixp4xx-osdg/ocf-linux-20041201.tar.gz
- Obtain OpenSSL v0.9.7d
http://www.openssl.org/source/openssl-0.9.7d.tar.gz
~~~~
NOTE: You must use Intel® IXP400 software w/Crypto support if you want to take
advantage of the NPE hardware Crypto acceleration.
~~~~
2. Set up and verify the baseline MVL3.1 kernel with Intel® IXP400
Software v1.4
================================================================
Copy the MVL3.1 kernel to a working directory.
Install the IXP400 Software v1.4 with Crypto per the release notes.
Verify the Linux kernel compiles, loads, boots and NFS mounts the root file
system. Verify the ixp0/1 Ethernet ports operate properly.
Verify OpenSSL operation by running "openssl speed". This will report the
non/OCF enabled OpenSSL performance. Keep this as baseline to monitor the
performance increase.
3. Enable the Crypto support in the Ethernet device driver
==========================================================
There are two basic changes required to support using the OCF driver with
IXP400 Software:
1. The Ethernet device driver must load the CRYPTO NPE image
2. call ixCryptoAccInit() in the module init just before ethacc_init().
in the Ethernet device driver/
This can be easily accomplished by using the Ethernet device driver patch
"ixp425_1.4_eth.patch" provided in the FreeS/WAN support
- freeswan1_99_patch_IXP400_1_4_MVL3_0.tar.gz
To get the patch and un-tar the file
tar xzvf freeswan1_99_patch_IXP400_1_4_MVL3_0.tar.gz
open_source_freeswan_release/ixp425_1.4_eth.patch
Then apply the patch
cd linux/drivers
patch -p0 < ~/open_source_freeswan_release/ixp425_1.4_eth.patch
NOTE: When the patch is applied, HUNK/success notifications appear.
4. Integrate the OCF support
=============================
- un-tar the OCF-Linux source files
tar xzvf ocf-linux-<rel-date>.tar.gz
This creates the files
ocf-linux-20041201
|-- README
|-- README.sglinux
|-- crypto-tools.patch
|-- crypto-tools.tar.gz
|-- ocf-linux-2.4.28.patch
|-- ocf-linux.tar.gz
|-- ssh.patch
`-- ssl.patch
~~~~~
NOTE: <rel-date> is the "release date". This readme was written based on
ocf-linux-20041201. Content may change for later releases. Please
consult the readme for updates. The 20041201 release supports
generic Linux kernels (with appropriate Crypto upgrade) SnapGear* Linux
3.1.1 and 3.1.6 distributions. Refer to the README files for the
abbreviated/adjunct instructions.
The content in this file was written/verified using the Crypto support
from the Linux 2.4.26 kernel. Should you desire to use the 2.4.28
kernel Crypto you will need to modify your steps accordingly. The
patch ocf-linux-2.4.28.patch performs some of the steps. This expects
the OCF support to be under the Crypto directory.
~~~~~
- Modify the Linux* include file miscdevice.h
---------------------------------------
Edit the miscdevice.h file and add the define
#define CRYPTODEV_MINOR70/* OpenBSD cryptographic framework */
This adds the minor number of the OCF Cryptodev driver.
- Set up the kernel config
--------------------------
Add a CONFIG entries to arch/arm/config.in
tristate 'OCF (Open Cryptographic Framework)' CONFIG_OCF_OCF
dep_tristate ' cryptodev (user space support)' CONFIG_OCF_CRYPTODEV $CONFIG_OCF_OCF
dep_tristate ' cryptosoft (software crypto engine)' CONFIG_OCF_CRYPTOSOFT $CONFIG_OCF_OCF
dep_tristate ' safenet (HW crypto engine)' CONFIG_OCF_SAFE $CONFIG_OCF_OCF
dep_tristate ' IXP4xx (HW crypto engine)' CONFIG_OCF_IXP4XX $CONFIG_OCF_OCF
- Update the MVL3.1 Crypto support
----------------------------------
The MVL3.1 kernel in based on Linux 2.4.20. The Crypto source must be updated
to use at least Crypto support available in Linux 2.4.26.
If you have an MVL support account you can request a patch that will update
the MVL3.1 Linux Crypto support. Contact MontaVista support via email
To: Support@mvista.com
RE: SUBMIT: Request patch to update the IXDP425 LSP crypto support to 2.4.26
You can also choose to do this on your own by using the linux-2.4.26/crypto
code.
Replace the current crypto directory files
include/linux/crypto.h and kmap_types.h to build the kernel Crypto
support.
Get and un-tar the linux-2.4.26 kernel
wget http://www.kernel.org/pub/linux/kernel/v2.4/linux-2.4.26.tar.gz
tar xzvf linux-2.4.26.tar.gz
Save any of the original files and make a soft link to the new crypto files
using commands such as:
cd linux-2.4.20_mvl31
mv crypto/ crypto-orig/
mv include/linux/crypto.h include/linux/crypto-orig.h
NOTE: kmap-types.h is not in include/asm-arm/ and must be copied from the
include/asm-i386 directory.
ln -s ~/kernel/linux-2.4.26/crypto/ crypto
ln -s ~/kernel/linux-2.4.26/include/linux/crypto.h include/linux/crypto.h
cp ~/kernel/linux-2.4.26/include/asm-i386/kmap_types.h include/asm-arm/.
- Un-tar the OCF Crypto driver
-----------------------------
Go to the drivers directory of the kernel and un-tar the OCF support
file.
cd drivers
tar xzvf ~/ocf-linux-<rel-date>/ocf-linux.tar.gz
This un-tars to create the files
ocf
|-- Makefile
|-- TODO
|-- criov.c
|-- crypto.c
|-- cryptodev.c
|-- cryptodev.h
|-- cryptosoft.c
|-- hifn
| |-- hifn7751.c
| |-- hifn7751reg.h
| `-- hifn7751var.h
|-- ixp4xx
| `-- ixp4xx.c
|-- safe
| |-- safe.c
| |-- safereg.h
| `-- safevar.h
`-- uio.h
. Edit the kernel drivers Makefile
----------------------------------
Edit the drivers/Makefile to add the ocf directory to the make in the
section of the make that is enabled by "ifdef CONFIG_IXP425_CSR"
subdir-$(CONFIG_OCF_OCF)+= ocf
. Edit the drivers/ocf/makefiles
--------------------------------
The makefiles are set up to use the "module" build system, and the include
paths need to use the settings that are specific to the MVL3.1 environment
setting. So, modify drivers/ocf/ixp/Makefile and change the path in the
two EXTRA_CFLAGS macros to use the IX_XSCALE_SW environment variable.
For example:
EXTRA_CFLAGS += -I$(IX_XSCALE_SW)/src/include
EXTRA_CFLAGS += -I$(IX_XSCALE_SW)/src/linux
5. Configure and build the kernel
---------------------------------
make def-config
make menuconfig
When menu config starts to navigate to the menu
System Type --->IXP4xx Implementation Options
select module for the options...
<M> Build IXP425 Access Library
<M> OCF (Open Cryptographic Framework) (NEW)
The dependent config choices appear. Then select module for the option...
<M> cryptodev (user space support)
<M> cryptosoft (software crypto engine)
< > safenet (HW crypto engine)
<M> IXP4xx (HW crypto engine)
back out to the main menu then select
Cryptographic options --->
Set all choices to Y except the "test" module
~~~~~
Note: Crypto MUST be compiled into the kernel and OCF support should be
compiled as a module.
~~~~~
Exit saving changes
NOTE: You can verify the OCF config values are in .config by using grep.
[homer@simsun linux-2.4.20_mvl31$ grep "OCF" .config
CONFIG_OCF_OCF=m
CONFIG_OCF_CRYPTODEV=m
CONFIG_OCF_CRYPTOSOFT=m
# CONFIG_OCF_SAFE is not set
CONFIG_OCF_IXP4XX=m
After the kernel is configured, make the kernel and modules then install using
commands such as the following:
make dep zImage modules
su
make modules_install
exit
6. Set up the Crypto device driver node
--------------------------------------
The device driver node must be created. This can be in the NFS mount target
or at run time. The steps below create the node in the NFS mounted filesystem.
su
cd /opt/montavista/pro/devkit/arm/xscale_be/target
mknod dev/crypto c 10 70
ls dev/cry* -la
crw-r--r-- 1 root root 10, 70 Nov 22 09:22 dev/crypto
7. Set up OpenSSL
----------------
- Get the source
----------------
wget http://www.openssl.org/source/openssl-0.9.7d.tar.gz
- Extract and patch
-------------------
tar xzvf src/openssl-0.9.7d.tar.gz
ln -s openssl-0.9.7d openssl
patch -p0 < ssl.patch
The patch to openssl enables cryptodev support as an ENGINE in OpenSSL.
- Configure and Build
---------------------
Place the cryptodev.h in the target include location
cd linux/drivers/ocf
su
mkdir /opt/montavista/pro/devkit/arm/xscale_be/target/usr/include/crypto
cp crytodev.h /opt/montavista/pro/devkit/arm/xscale_be/target/usr/include/crypto
~~~~~
NOTE: In order to build OpenSSL applications, make sure that cryptodev.h
is installed as crypto/cryptodev.h in your include directory
~~~~~
./Configure linux-elf-arm -shared --prefix=/opt/montavista/pro/devkit/arm/xscale_be/target/usr/
To build for the Intel XScale core you must modify the Makefile so that CC,
CFLAG, EX_LIBS, AR and RANLIB macros are correct for cross-compilation.
In the CFLAG macro change -DL_ENDIAN to -DB_ENDIAN
Change the other macros to read:
CC=xscale_be-gcc
EX_LIBS= -ldl
AR=xscale_be-ar $(ARFLAGS) r
RANLIB= xscale_be-ranlib
Then make
- Basic Install
---------------
These steps copy and set up the necessary libraries
in the MVL3.1 NFS target root filesystem.
su
cd /opt/montavista/pro/devkit/arm/xscale_be/target/usr/lib
# back up the existing libs
mv libcrypto.so.0.9.7 libcrypto.so.0.9.7b
mv libssl.so.0.9.7 libssl.so.0.0.9.7b
mv libssl.a libssl.a.0.9.7b
mv libcrypto.a libcrypto.a.0.7.9b
cp openssl/libcrypto.so.0.9.7 .
cp openssl/libssl.so.0.9.7 .
cp openssl/libssl.a .
cp openssl/libcrypto.a .
cd /opt/montavista/pro/devkit/arm/xscale_be/target/
cd /opt/montavista/pro/devkit/arm/xscale_be/target/usr/bin
# this moves the old OpenSSL
mv openssl openssl.0.9.7b
# copy the rebuilt application
cp openssl/apps/openssl .
- Verify operation
------------------
Verify the operation of the driver and Engine by using the following OpenSSL
speed command:
openssl speed -evp des -engine cryptodev
See the readme provided with the OCF drivers for additional detail.
8. Resources, links, and Q/A
---------------------------
Consult these sites for information
CryptoDev and Crypto API for Linux -
home page: http://www.logix.cz/michal/devel/cryptodev/
Mailing list: http://lists.logix.cz/mailman/listinfo/cryptoapi
uCdot -
Home page: http://www.uCdot.org
SourceForge*: IXP4xx-osgd -
home page: http://ixp4xx-osdg.sourceforge.net
Project page: http://sourceforge.net/projects/ixp4xx-osdg/
Forums: http://sourceforge.net/forum/forum.php?forum_id=311814
