[package] udev: bump to 173
[openwrt.git] / target / linux / generic / files / crypto / ocf / README
1 ###########################
2 README - ocf-linux-20100530
3 ###########################
4
5 This README provides instructions for getting ocf-linux compiled and
6 operating in a generic linux environment. Other information on the project
7 can be found at the home page:
8
9 http://ocf-linux.sourceforge.net/
10
11 Embedded systems and applications requiring userspace acceleration will need
12 to patch the kernel source to get full OCF support. See "Adding OCF to
13 linux source" below. Otherwise the "OCF Quickstart" that follows is the
14 easiest way to get started.
15
16 If your goal is to accelerate Openswan on Ubuntu or CentOS, you may find
17 that the required binaries are already available on openswan.org:
18
19 ftp://ftp.openswan.org/ocf/
20 ftp://ftp.openswan.org/openswan/binaries/ubuntu/
21
22 #####################################################
23 OCF Quickstart for Ubuntu/Others (including Openswan)
24 #####################################################
25
26 This section provides instructions on how to quickly add kernel only support
27 for OCF to a GNU/Linux system. It is only suitable for in-kernel use such as
28 Openswan MAST/KLIPS.
29
30 If the target is an embedded system, or, userspace acceleration of
31 applications such as OpenVPN and OpenSSL, the section below titled
32 "Adding OCF to linux source" is more appropriate.
33
34 Before building kernel only support for OCF ensure that the appropriate
35 linux-headers package is installed:
36
37 cd ocf
38 make ocf_modules
39 sudo make ocf_install
40 OCF_DIR=`pwd` # remember where OCF sources were built
41
42 At this point the ocf, cryptosoft, ocfnull, hifn7751 and ocf-bench modules
43 should have been built and installed. The OCF installation can be tested
44 with the following commands:
45
46 modprobe ocf
47 modprobe cryptosoft
48 modprobe ocf-bench
49 dmesg | tail -5
50
51 The final modprobe of ocf-bench will fail, this is intentional as ocf-bench
52 is a short lived module that tests in-kernel performance of OCF. If
53 everything worked correctly the "dmesg | tail -5" should include a line
54 like:
55
56 [ 583.128741] OCF: 45133 requests of 1488 bytes in 251 jiffies (535.122 Mbps)
57
58 This shows the in-kernel performance of OCF using the cryptosoft driver.
59 For addition driver load options, see "How to load the OCF modules" below.
60
61 If the intention is to run an OCF accelerated Openswan (KLIPS/MAST) then use
62 these steps to compile openswan downloaded from openswan.org (2.6.34 or later).
63
64 tar xf openswan-2.6.34.tar.gz
65 cd openswan-2.6.34
66 make programs
67 make KERNELSRC=/lib/modules/`uname -r`/build \
68 KBUILD_EXTRA_SYMBOLS=$OCF_DIR/Module.symvers \
69 MODULE_DEF_INCLUDE=`pwd`/packaging/ocf/config-all.hmodules \
70 MODULE_DEFCONFIG=`pwd`/packaging/ocf/defconfig \
71 module
72 sudo make KERNELSRC=/lib/modules/`uname -r`/build \
73 KBUILD_EXTRA_SYMBOLS=$OCF_DIR/Module.symvers \
74 MODULE_DEF_INCLUDE=`pwd`/packaging/ocf/config-all.hmodules \
75 MODULE_DEFCONFIG=`pwd`/packaging/ocf/defconfig \
76 install minstall
77
78 The rest of this document is only required for more complex build
79 requirements.
80
81 ##########################
82 Adding OCF to linux source
83 ##########################
84
85 It is recommended that OCF be built as modules as it increases the
86 flexibility and ease of debugging the system.
87
88 Ensure that the system has /dev/crypto for userspace access to OCF:
89
90 mknod /dev/crypto c 10 70
91
92 Generate the kernel patches and apply the appropriate one.
93
94 cd ocf
95 make patch
96
97 This will provide three files:
98
99 linux-2.4.*-ocf.patch
100 linux-2.6.*-ocf.patch
101 ocf-linux-base.patch
102
103 If either of the first two patches applies to the targets kernel, then one
104 of the following as required:
105
106 cd linux-2.X.Y; patch -p1 < linux-2.4.*-ocf.patch
107 cd linux-2.6.Y; patch -p1 < linux-2.6.*-ocf.patch
108
109 Otherwise, locate the appropriate kernel patch in the patches directory and
110 apply that as well as the ocf-linux-base.patch using '-p1'.
111
112 When using a linux-2.4 system on a non-x86 platform, the following may be
113 required to build cryptosoft:
114
115 cp linux-2.X.x/include/asm-i386/kmap_types.h linux-2.X.x/include/asm-YYY
116
117 When using cryptosoft, for simplicity, enable all the crypto support in the
118 kernel except for the test driver. Likewise for the OCF options. Do not
119 enable OCF crypto drivers for HW that is not present (for example the ixp4xx
120 driver will not compile on non-Xscale systems).
121
122 Make sure that cryptodev.h from the ocf directory is installed as
123 crypto/cryptodev.h in an include directory that is used for building
124 applications for the target platform. For example on a host system that
125 might be:
126
127 /usr/include/crypto/cryptodev.h
128
129 Patch the openssl-0.9.8r code the openssl-0.9.8r.patch from the patches
130 directory. There are many older patch versions in the patches directory
131 if required.
132
133 The openssl patches provide the following functionality:
134
135 * enables --with-cryptodev for non BSD systems
136 * adds -cpu option to openssl speed for calculating CPU load under linux
137 * fixes null pointer in openssl speed multi thread output.
138 * fixes test keys to work with linux crypto's more stringent key checking.
139 * adds MD5/SHA acceleration (Ronen Shitrit), only enabled with the
140 --with-cryptodev-digests option
141 * fixes bug in engine code caching.
142
143 Build the crypto-tools directory for the target to obtain a userspace
144 testing tool call cryptotest.
145
146 ###########################
147 How to load the OCF modules
148 ###########################
149
150 First insert the base modules (cryptodev is optional, it is only used
151 for userspace acceleration):
152
153 modprobe ocf
154 modprobe cryptodev
155
156 Load the software OCF driver with:
157
158 modprobe cryptosoft
159
160 and zero or more of the OCF HW drivers with:
161
162 modprobe safe
163 modprobe hifn7751
164 modprobe ixp4xx
165 ...
166
167 All the drivers take a debug option to enable verbose debug so that
168 OCF operation may be observed via "dmesg" or the console. For debug
169 load the modules as:
170
171 modprobe ocf crypto_debug=1
172 modprobe cryptodev cryptodev_debug=1
173 modprobe cryptosoft swcr_debug=1
174
175 More than one OCF crypto driver may be loaded but then there is no
176 guarantee as to which will be used (other than a preference for HW
177 drivers over SW drivers by most applications).
178
179 It is also possible to enable debug at run time on linux-2.6 systems
180 with the following:
181
182 echo 1 > /sys/module/ocf/parameters/crypto_debug
183 echo 1 > /sys/module/cryptodev/parameters/cryptodev_debug
184 echo 1 > /sys/module/cryptosoft/parameters/swcr_debug
185 echo 1 > /sys/module/hifn7751/parameters/hifn_debug
186 echo 1 > /sys/module/safe/parameters/safe_debug
187 echo 1 > /sys/module/ixp4xx/parameters/ixp_debug
188 ...
189
190 The ocf-bench driver accepts the following parameters:
191
192 request_q_len - Maximum number of outstanding requests to OCF
193 request_num - run for at least this many requests
194 request_size - size of each request (multiple of 16 bytes recommended)
195 request_batch - enable OCF request batching
196 request_cbimm - enable OCF immediate callback on completion
197
198 For example:
199
200 modprobe ocf-bench request_size=1024 request_cbimm=0
201
202 #######################
203 Testing the OCF support
204 #######################
205
206 run "cryptotest", it should do a short test for a couple of
207 des packets. If it does everything is working.
208
209 If this works, then ssh will use the driver when invoked as:
210
211 ssh -c 3des username@host
212
213 to see for sure that it is operating, enable debug as defined above.
214
215 To get a better idea of performance run:
216
217 cryptotest 100 4096
218
219 There are more options to cryptotest, see the help.
220
221 It is also possible to use openssl to test the speed of the crypto
222 drivers.
223
224 openssl speed -evp des -engine cryptodev -elapsed
225 openssl speed -evp des3 -engine cryptodev -elapsed
226 openssl speed -evp aes128 -engine cryptodev -elapsed
227
228 and multiple threads (10) with:
229
230 openssl speed -evp des -engine cryptodev -elapsed -multi 10
231 openssl speed -evp des3 -engine cryptodev -elapsed -multi 10
232 openssl speed -evp aes128 -engine cryptodev -elapsed -multi 10
233
234 for public key testing you can try:
235
236 cryptokeytest
237 openssl speed -engine cryptodev rsa -elapsed
238 openssl speed -engine cryptodev dsa -elapsed
239
240
241 #############################
242 #
243 # David McCullough
244 # david_mccullough@mcafee.com
245 #
246 #############################
This page took 0.055376 seconds and 5 git commands to generate.