]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
1 | ======================================================================== |
2 | README for Intel(R) Multi-Buffer Crypto for IPsec Library | |
3 | ||
4 | March 2018 | |
5 | ======================================================================== | |
6 | ||
7 | ||
8 | Contents | |
9 | ======== | |
10 | ||
11 | - Overview | |
12 | - Processor Extensions | |
13 | - Recommendations | |
14 | - Package Content | |
15 | - Compilation | |
16 | - Installation | |
17 | - Legal Disclaimer | |
18 | ||
19 | ||
20 | Overview | |
21 | ======== | |
22 | Intel Multi-Buffer Crypto for IPsec Library is highly-optimized | |
23 | software implementations of the core cryptographic processing for IPsec, | |
24 | which provides industry-leading performance on a range of Intel(R) Processors. | |
25 | ||
26 | For information on how to build and use this library, see the | |
27 | Intel White Paper: | |
28 | "Fast Multi-buffer IPsec Implementations on Intel Architecture Processors". | |
29 | Jim Guilford, Sean Gulley, et. al. | |
30 | ||
31 | The easiest way to find it is to search the Internet for the title and | |
32 | Intel White Paper. | |
33 | ||
34 | Table 1. List of supported cipher algorithms and their implementations. | |
35 | +------------------------------------------------------------+ | |
36 | | | Implementation | | |
37 | | Encryption +--------------------------------------------| | |
38 | | | x86_64 | SSE | AVX | AVX2 | AVX512 | | |
39 | |---------------+--------+--------+--------+--------+--------| | |
40 | | AES128-GCM | N | Y by8 | Y by8 | Y by8 | N | | |
41 | | AES192-GCM | N | Y by8 | Y by8 | Y by8 | N | | |
42 | | AES256-GCM | N | Y by8 | Y by8 | Y by8 | N | | |
43 | | AES128-CCM | Y(1) | Y by4 | Y by8 | N | N | | |
44 | | AES128-CBC | N | Y(2) | Y(4) | N | N | | |
45 | | AES192-CBC | N | Y(2) | Y(4) | N | N | | |
46 | | AES256-CBC | N | Y(2) | Y(4) | N | N | | |
47 | | AES128-CTR | N | Y by4 | Y by8 | N | N | | |
48 | | AES192-CTR | N | Y by4 | Y by8 | N | N | | |
49 | | AES256-CTR | N | Y by4 | Y by8 | N | N | | |
50 | | NULL | Y | N | N | N | N | | |
51 | | AES128-DOCSIS | N | Y(3) | Y(5) | N | N | | |
52 | | DES-DOCSIS | Y | N | N | N | Y x16 | | |
53 | | 3DES | Y | N | N | N | Y x16 | | |
54 | | DES | Y | N | N | N | Y x16 | | |
55 | +------------------------------------------------------------+ | |
56 | ||
57 | Notes: | |
58 | (1) - AES128-CCM scheduler code is implemented in C at the moment. | |
59 | Underlaying AES128-CTR algorithm utlizes SSE and AVX. | |
60 | (2,3) - decryption is by4 and encryption is x4 | |
61 | (4,5) - decryption is by8 and encryption is x8 | |
62 | ||
63 | Legend: | |
64 | byY - single buffer Y blocks at a time | |
65 | xY - Y buffers at a time | |
66 | ||
67 | As an example of how to read table 1 and 2, if one uses AVX512 interface | |
68 | to perform AES128-CBC encryption then there is no native AVX512 | |
69 | implementation for this cipher. In such case, the library uses best | |
70 | available implementation which is AVX for AES128-CBC. | |
71 | ||
72 | ||
73 | Table 2. List of supported integrity algorithms and their implementations. | |
74 | +----------------------------------------------------------------+ | |
75 | | | Implementation | | |
76 | | Integrity +--------------------------------------------| | |
77 | | | x86_64 | SSE | AVX | AVX2 | AVX512 | | |
78 | |-------------------+--------+--------+--------+--------+--------| | |
79 | | AES-XCBC-96 | N | Y x4 | Y x8 | N | N | | |
80 | | HMAC-MD5-96 | Y(1) | Y x4x2 | Y x4x2 | Y x8x2 | N | | |
81 | | HMAC-SHA1-96 | N | Y(4)x4 | Y x4 | Y x8 | Y x16 | | |
82 | | HMAC-SHA2-224_112 | N | Y(4)x4 | Y x4 | Y x8 | Y x16 | | |
83 | | HMAC-SHA2-256_128 | N | Y(4)x4 | Y x4 | Y x8 | Y x16 | | |
84 | | HMAC-SHA2-384_192 | N | Y x2 | Y x2 | Y x4 | Y x8 | | |
85 | | HMAC-SHA2-512_256 | N | Y x2 | Y x2 | Y x4 | Y x8 | | |
86 | | AES128-GMAC | N | Y by8 | Y by8 | Y by8 | N | | |
87 | | AES192-GMAC | N | Y by8 | Y by8 | Y by8 | N | | |
88 | | AES256-GMAC | N | Y by8 | Y by8 | Y by8 | N | | |
89 | | NULL | N | N | N | N | N | | |
90 | | AES128-CCM | Y(2) | Y x4 | Y x8 | N | N | | |
91 | | AES128-CMAC-96 | Y(3) | Y x4 | Y x8 | N | N | | |
92 | +----------------------------------------------------------------+ | |
93 | ||
94 | Notes: | |
95 | (1) - MD5 over one block implemented in C | |
96 | (2,3) - AES128-CCM and AES128-CMAC scheduler code is implemented in C. | |
97 | Underlaying AES128-CBC algorithm utlizes SSE and AVX. | |
98 | (4) - Implementation using SHANI extentions is x2 | |
99 | ||
100 | Legend: | |
101 | byY - single buffer Y blocks at a time | |
102 | xY - Y buffers at a time | |
103 | ||
104 | Table 3. Encryption and integrity algorithm combinations | |
105 | +---------------------------------------------------------------------+ | |
106 | | Encryption | Allowed Integrity Algorithms | | |
107 | |---------------+-----------------------------------------------------| | |
108 | | AES128-GCM | AES128-GMAC | | |
109 | |---------------+-----------------------------------------------------| | |
110 | | AES192-GCM | AES192-GMAC | | |
111 | |---------------+-----------------------------------------------------| | |
112 | | AES256-GCM | AES256-GMAC | | |
113 | |---------------+-----------------------------------------------------| | |
114 | | AES128-CCM | AES128-CCM | | |
115 | |---------------+-----------------------------------------------------| | |
116 | | AES128-CBC, | AES-XCBC-96, | | |
117 | | AES192-CBC, | HMAC-SHA1-96, HMAC-SHA2-224_112, HMAC-SHA2-256_128, | | |
118 | | AES256-CBC, | HMAC-SHA2-384_192, HMAC-SHA2-512_256, | | |
119 | | AES128-CTR, | AES128-CMAC-96, | | |
120 | | AES192-CTR, | NULL | | |
121 | | AES256-CTR, | | | |
122 | | NULL, | | | |
123 | | AES128-DOCSIS,| | | |
124 | | DES-DOCSIS, | | | |
125 | | 3DES, | | | |
126 | | DES, | | | |
127 | +---------------+-----------------------------------------------------+ | |
128 | ||
129 | ||
130 | Processor Extensions | |
131 | ==================== | |
132 | ||
133 | Table 4. Processor extensions used in the library | |
134 | +-------------------------------------------------------------------------+ | |
135 | | Algorithm | Interface | Extensions | | |
136 | |-------------------+-----------+-----------------------------------------| | |
137 | | HMAC-SHA1-96, | AVX512 | AVX512F, AVX512BW, AVX512VL | | |
138 | | HMAC-SHA2-224_112,| | | | |
139 | | HMAC-SHA2-256_128,| | | | |
140 | | HMAC-SHA2-384_192,| | | | |
141 | | HMAC-SHA2-512_256 | | | | |
142 | |-------------------+-----------+-----------------------------------------| | |
143 | | DES, 3DES, | AVX512 | AVX512F, AVX512BW | | |
144 | | DOCSIS-DES | | | | |
145 | |-------------------+-----------+-----------------------------------------| | |
146 | | HMAC-SHA1-96, | SSE | SHANI | | |
147 | | HMAC-SHA2-224_112,| | - presence is autodetected and library | | |
148 | | HMAC-SHA2-256_128,| | falls back to SSE implementation | | |
149 | | HMAC-SHA2-384_192,| | if not present | | |
150 | | HMAC-SHA2-512_256 | | | | |
151 | |-------------------+-----------+-----------------------------------------| | |
152 | ||
153 | ||
154 | Recommendations | |
155 | =============== | |
156 | ||
157 | Legacy or to be avoided algorithms listed in the table below are implemented | |
158 | in the library in order to support legacy applications. Please use corresponding | |
159 | alternative algorithms instead. | |
160 | ||
161 | +----------------------------------------------------------+ | |
162 | | # | Algorithm | Recommendation | Alternative | | |
163 | |---+--------------------+----------------+----------------| | |
164 | | 1 | DES encryption | Avoid | AES encryption | | |
165 | |---+--------------------+----------------+----------------| | |
166 | | 2 | 3DES encryption | Avoid | AES encryption | | |
167 | |---+--------------------+----------------+----------------| | |
168 | | 3 | HMAC-MD5 integrity | Legacy | HMAC-SHA1 | | |
169 | +----------------------------------------------------------+ | |
170 | ||
171 | ||
172 | Package Content | |
173 | =============== | |
174 | ||
175 | LibTestApp - sample application using the library interface | |
176 | sse - Intel(R) SSE optimized routines | |
177 | avx - Intel(R) AVX optimized routines | |
178 | avx2 - Intel(R) AVX2 optimized routines | |
179 | avx512 - Intel(R) AVX512 optimized routines | |
180 | ||
181 | Compilation | |
182 | =========== | |
183 | ||
184 | Linux (64-bit only) | |
185 | ------------------- | |
186 | ||
187 | Required tools: | |
188 | - GNU make | |
189 | - NASM version 2.12.02 (or newer) | |
190 | - gcc (GCC) 4.8.3 (or newer) | |
191 | ||
192 | Shared library: | |
193 | > make | |
194 | ||
195 | Static library: | |
196 | > make SHARED=n | |
197 | ||
198 | Clean the build: | |
199 | > make clean | |
200 | or | |
201 | > make clean SHARED=n | |
202 | ||
203 | Build with debugging information: | |
204 | > make DEBUG=y | |
205 | ||
206 | Note: Building with debugging information is not advised for production use. | |
207 | ||
208 | Windows (x64 only) | |
209 | ------------------ | |
210 | ||
211 | Required tools: | |
212 | - Microsoft (R) Visual Studio 2010: | |
213 | - NMAKE: Microsoft (R) Program Maintenance Utility Version 10.00.30319.01 | |
214 | - CL: Microsoft (R) C/C++ Optimizing Compiler Version 16.00.30319.01 for x64 | |
215 | - LIB: Microsoft (R) Library Manager Version 10.00.30319.01 | |
216 | - LINK: Microsoft (R) Incremental Linker Version 10.00.30319.01 | |
217 | - NASM version 2.12.02 (or newer) | |
218 | ||
219 | Shared library (DLL): | |
220 | > nmake /f win_x64.mak | |
221 | ||
222 | Static library: | |
223 | > nmake /f win_x64.mak SHARED=n | |
224 | ||
225 | Clean the build: | |
226 | > nmake /f win_x64.mak clean | |
227 | or | |
228 | > nmake /f win_x64.mak clean SHARED=n | |
229 | ||
230 | Build with debugging information: | |
231 | > nmake /f win_x64.mak DEBUG=y | |
232 | ||
233 | Note: Building with debugging information is not advised for production use. | |
234 | ||
235 | Installation | |
236 | ============ | |
237 | ||
238 | Linux (64-bit only) | |
239 | ------------------- | |
240 | ||
241 | First compile the library and then install: | |
242 | > make | |
243 | > sudo make install | |
244 | ||
245 | To uninstall the library run: | |
246 | > sudo make uninstall | |
247 | ||
248 | If you want to change install location then define PREFIX | |
249 | > sudo make install PREFIX=<path> | |
250 | ||
251 | If there is no need to run ldconfig at install stage please use NOLDCONFIG=y option. | |
252 | > sudo make install NOLDCONFIG=y | |
253 | ||
254 | If library was compiled as an archive (not a default option) then install it | |
255 | using SHARED=n option: | |
256 | > sudo make install SHARED=n | |
257 | ||
258 | Windows (x64 only) | |
259 | ------------------ | |
260 | ||
261 | First compile the library and then install from a command prompt in | |
262 | administrator mode: | |
263 | > nmake /f win_x64.mak | |
264 | > nmake /f win_x64.mak install | |
265 | ||
266 | To uninstall the library run: | |
267 | > nmake /f win_x64.mak uninstall | |
268 | ||
269 | If you want to change install location then define PREFIX (default C:\Program Files) | |
270 | > nmake /f win_x64.mak install PREFIX=<path> | |
271 | ||
272 | If library was compiled as a static library (not a default option) then install it | |
273 | using SHARED=n option: | |
274 | > nmake /f win_x64.mak install SHARED=n | |
275 | ||
276 | Legal Disclaimer | |
277 | ================ | |
278 | ||
279 | THIS SOFTWARE IS PROVIDED BY INTEL"AS IS". NO LICENSE, EXPRESS OR | |
280 | IMPLIED, BY ESTOPPEL OR OTHERWISE, TO ANY INTELLECTUAL PROPERTY RIGHTS | |
281 | ARE GRANTED THROUGH USE. EXCEPT AS PROVIDED IN INTEL'S TERMS AND | |
282 | CONDITIONS OF SALE, INTEL ASSUMES NO LIABILITY WHATSOEVER AND INTEL | |
283 | DISCLAIMS ANY EXPRESS OR IMPLIED WARRANTY, RELATING TO SALE AND/OR | |
284 | USE OF INTEL PRODUCTS INCLUDING LIABILITY OR WARRANTIES RELATING TO | |
285 | FITNESS FOR A PARTICULAR PURPOSE, MERCHANTABILITY, OR INFRINGEMENT | |
286 | OF ANY PATENT, COPYRIGHT OR OTHER INTELLECTUAL PROPERTY RIGHT. |