-
Notifications
You must be signed in to change notification settings - Fork 16
/
Copy pathREADME.engine
242 lines (183 loc) · 8.16 KB
/
README.engine
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
© 2023 NVIDIA Corporation & affiliates.
License: BSD-3-Clause
BlueField PKA engine 1.0
Author, Khalil Blaiech <kblaiech@mellanox.com>
===============================================================================
Overview
===============================================================================
The BlueField PKA engine is a set dynamically-loadable OpenSSL engine that
interfaces with the BlueField PKA hardware. It provides support for RSA
operation such as signature generation and verification.
The BlueField PKA engine might be integrated with OpenSSL 1.0 and 1.1.
Earlier versions may or may not work; use at your own risk!
Bluefield PKA engine can also be used with OpenSSL 3.0 provided OpenSSL 3.0
is built with compatibility for OpenSSL 1.1. This can be done by passing the
option "--api=1.1.0" during the configure step for OpenSSL 3.0.
Once OpenSSL 3.0 is built with compatibility for OpenSSL 1.1, follow the steps
below on how to build, install and use the Bluefield PKA engine.
Currently, OpenSSL 3.0 is in alpha release (alpha12), so it is not a stable
release; some of the advertised features might not work!
===============================================================================
Important Notes
===============================================================================
* The PKA engine requires the PKA libraries and drivers installed.
Look at 'README' to build and install PKA libraries. Note that
the PKA engine is pre-installed:
On Yocto Poky systems, the engine is installed into
'/usr/lib64/engines-1.1/libbfengine.so'
On CentOS systems, the engine is installed into
'/usr/lib64/libbfengine.so.1.1.0'
On Ubuntu systems, the engine is installed into
'/usr/lib/aarch64-linux-gnu/libbfengine.so.1.1.0'
On Debian systems, the engine is installed into
'/usr/lib/aarch64-linux-gnu/libbfengine.so.1.1.0'
Users are invited to install the shared object file into the
appropriate destination directory within the OpenSSL engine folder,
if needed. This depends on OpennSSL installation and settings.
* The PKA engine requires OpenSSL libraries, such as libcrypto and
libssl. Note that Yocto Poky, CentOS, Debian and Ubuntu systems have a pre-
installed openssl package:
On Yocto Poky systems:
# openssl version
OpenSSL 1.1.1g 21 Apr 2020
On CentOS systems:
# openssl version
OpenSSL 1.0.2k-fips 26 Jan 2017
On Ubuntu systems:
# openssl version
OpenSSL 1.1.1f 31 Mar 2020
On Debian systems:
# openssl version
OpenSSL 1.1.1d 10 Sep 2019
For native compilation, simply load the necessary libraries using
the appropriate tool set.
On CentOS systems:
# yum install openssl-devel
On Ubuntu systems:
# apt install openssl-devel
Cross compilation requires cross compiling the individual libraries.
In order for a cross compiled executable to run on a target system,
one must build the same version as that which is installed on the
target rootfs.
* OpenSSL version 1.1.1 is recommended. This is necessary in-order to
offload ECDH and ECDSA.
===============================================================================
How to build
===============================================================================
Build BlueField PKA engine module:
# cd <pka_engine_dir>
# make
# make install
===============================================================================
How to install
===============================================================================
The PKA engine module has to be installed within the engines folder
of the installed OpenSSL. This may vary depending on OpenSSL installation
as well as the Linux distribution.
Note that both Yocto Poky and CentOS have already the engine module
installed within the correct directory.
On Yocto Poky, the engine module is installed into
'/usr/lib64/engines-1.1/pka.so'
On CentOS, the engine module is installed into
'/usr/lib64/openssl/engines/libpka.so'
On Ubuntu, the engine module is installed into
'/usr/lib/aarch64-linux-gnu/engines-1.1/pka.so'
On Debian, the engine module is installed into
'/usr/lib/aarch64-linux-gnu/engines-1.1/pka.so'
If needed, install the engine module to OpenSSL 'engines' directory.
On Yocto Poky systems running default OpenSSL 1.1.1g:
# cd <pka_install_dir>/lib
# cp libbfengine.so.1.1.0 /usr/lib64/engines-1.1/
# cd /usr/lib64/engines-1.1/
# ln -s libbfengine.so.1.1.0 pka.so
On CentOS systems running default OpenSSL 1.0.2k-fips:
# cd <pka_install_dir>/lib
# cp libbfengine.so.1.1.0 /usr/lib64/openssl/engines/
# cd /usr/lib64/openssl/engines/
# ln -s libbfengine.so.1.1.0 libpka.so
On Ubuntu systems running default OpenSSL 1.1.1f:
# cd <pka_install_dir>/lib
# cp libbfengine.so.1.1.0 /usr/lib/aarch64-linux-gnu/engines-1.1/
# cd /usr/lib/aarch64-linux-gnu/engines-1.1/
# ln -s libbfengine.so.1.1.0 pka.so
On Debian systems running default OpenSSL 1.1.1d:
# cd <pka_install_dir>/lib
# cp libbfengine.so.1.1.0 /usr/lib/aarch64-linux-gnu/engines-1.1/
# cd /usr/lib/aarch64-linux-gnu/engines-1.1/
# ln -s libbfengine.so.1.1.0 pka.so
Note that OpenSSL 1.0 requires the prefix 'lib' to be appended to
the ID of the PKA engine, i.e. 'libpka.so'. OpenSSL 1.1 the module
name should be 'pka.so'; as same as the ID of the engine.
Please refer to Section "Important Notes" in order to locate the pre-built
engine module, in case the module didn't get built manually.
===============================================================================
How to load
===============================================================================
To load the BlueField PKA engine module into OpenSSL:
On Yocto Poky systems:
# openssl engine dynamic \
> -pre SO_PATH:/usr/lib64/engines-1.1/pka.so \
> -pre ID:pka -pre LOAD
(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/usr/lib64/engines/libpka.so
[Success]: ID:pka
[Success]: LOAD
Loaded: (pka) BlueField PKA engine support
[ available ]
On CentOS systems:
# openssl engine -t dynamic \
> -pre SO_PATH:/usr/lib64/openssl/engines/libpka.so \
> -pre ID:pka -pre LOAD
(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/usr/lib64/openssl/engines/libpka.so
[Success]: ID:pka
[Success]: LOAD
Loaded: (pka) BlueField PKA engine support
[ available ]
On Ubuntu systems:
# openssl engine dynamic \
> -pre SO_PATH:/usr/lib/aarch64-linux-gnu/engines-1.1/pka.so \
> -pre ID:pka -pre LOAD
(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/usr/lib/aarch64-linux-gnu/engines-1.1/pka.so
[Success]: ID:pka
[Success]: LOAD
Loaded: (pka) BlueField PKA engine support
[ available ]
On Debian systems:
# openssl engine dynamic \
> -pre SO_PATH:/usr/lib/aarch64-linux-gnu/engines-1.1/pka.so \
> -pre ID:pka -pre LOAD
(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/usr/lib/aarch64-linux-gnu/engines-1.1/pka.so
[Success]: ID:pka
[Success]: LOAD
Loaded: (pka) BlueField PKA engine support
[ available ]
Note that the option '-t' is omitted when working with OpenSSL 1.1,
since this cannot be used with option 'engine'.
Now, the BlueField PKA engine is ready to use; no need to reload the
engine across reboot.
To use the BlueField PKA engine, one may pass the option '-engine pka'
to dynamically load the module and enable hardware acceleration.
Examples:
1. RSA
# openssl speed -engine pka rsa512
engine "pka" set.
...
2. DSA
# openssl speed -engine pka dsa512
engine "pka" set.
...
3. ECDH
# openssl speed -engine pka ecdhp256
engine "pka" set.
...
4. ECDSA
# openssl speed -engine pka ecdsap256
engine "pka" set.
...
5. Random number generation (RNG)
# openssl rand -engine pka 512
engine "pka" set.
...