Readme for the MontaVista* Linux* 3.1 OpenSSL*/OCF and Intel? IXP400 Software v1.4 Integration

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_MINOR		70	/* 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

【深 度 阅 读】 相 关 文 章

·openssl之：BIO系列之7---BIO链的操作
·openssl之BIO系列之15---内存(mem)类型BIO
·openssl之BIO系列之16---BIO对(pair)类型BIO
·openssl之BIO系列之7---BIO链的操作