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