doc: announce removal of indirect mbuf check macro
[dpdk.git] / doc / guides / cryptodevs / openssl.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2016 Intel Corporation.
3
4 OpenSSL Crypto Poll Mode Driver
5 ===============================
6
7 This code provides the initial implementation of the openssl poll mode
8 driver. All cryptography operations are using Openssl library crypto API.
9 Each algorithm uses EVP interface from openssl API - which is recommended
10 by Openssl maintainers.
11
12 For more details about openssl library please visit openssl webpage:
13 https://www.openssl.org/
14
15 Features
16 --------
17
18 OpenSSL PMD has support for:
19
20 Supported cipher algorithms:
21
22 * ``RTE_CRYPTO_CIPHER_3DES_CBC``
23 * ``RTE_CRYPTO_CIPHER_AES_CBC``
24 * ``RTE_CRYPTO_CIPHER_AES_CTR``
25 * ``RTE_CRYPTO_CIPHER_3DES_CTR``
26 * ``RTE_CRYPTO_CIPHER_DES_DOCSISBPI``
27
28 Supported authentication algorithms:
29
30 * ``RTE_CRYPTO_AUTH_AES_GMAC``
31 * ``RTE_CRYPTO_AUTH_MD5``
32 * ``RTE_CRYPTO_AUTH_SHA1``
33 * ``RTE_CRYPTO_AUTH_SHA224``
34 * ``RTE_CRYPTO_AUTH_SHA256``
35 * ``RTE_CRYPTO_AUTH_SHA384``
36 * ``RTE_CRYPTO_AUTH_SHA512``
37 * ``RTE_CRYPTO_AUTH_MD5_HMAC``
38 * ``RTE_CRYPTO_AUTH_SHA1_HMAC``
39 * ``RTE_CRYPTO_AUTH_SHA224_HMAC``
40 * ``RTE_CRYPTO_AUTH_SHA256_HMAC``
41 * ``RTE_CRYPTO_AUTH_SHA384_HMAC``
42 * ``RTE_CRYPTO_AUTH_SHA512_HMAC``
43
44 Supported AEAD algorithms:
45
46 * ``RTE_CRYPTO_AEAD_AES_GCM``
47 * ``RTE_CRYPTO_AEAD_AES_CCM``
48
49
50 Installation
51 ------------
52
53 To compile openssl PMD, it has to be enabled in the config/common_base file
54 and appropriate openssl packages have to be installed in the build environment.
55
56 The newest openssl library version is supported:
57
58 * 1.0.2h-fips  3 May 2016.
59
60 Older versions that were also verified:
61
62 * 1.0.1f 6 Jan 2014
63 * 1.0.1 14 Mar 2012
64
65 For Ubuntu 14.04 LTS these packages have to be installed in the build system:
66
67 .. code-block:: console
68
69     sudo apt-get install openssl
70     sudo apt-get install libc6-dev-i386 # for i686-native-linuxapp-gcc target
71
72 This code was also verified on Fedora 24.
73 This code has NOT been verified on FreeBSD yet.
74
75 Initialization
76 --------------
77
78 User can use app/test application to check how to use this pmd and to verify
79 crypto processing.
80
81 Test name is cryptodev_openssl_autotest.
82 For performance test cryptodev_openssl_perftest can be used.
83
84 To verify real traffic l2fwd-crypto example can be used with this command:
85
86 .. code-block:: console
87
88         sudo ./build/l2fwd-crypto -l 0-1 -n 4 --vdev "crypto_openssl"
89         --vdev "crypto_openssl"-- -p 0x3 --chain CIPHER_HASH
90         --cipher_op ENCRYPT --cipher_algo AES_CBC
91         --cipher_key 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:0f
92         --iv 00:01:02:03:04:05:06:07:08:09:0a:0b:0c:0d:0e:ff
93         --auth_op GENERATE --auth_algo SHA1_HMAC
94         --auth_key 11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
95         :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
96         :11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11:11
97
98 Limitations
99 -----------
100
101 * Maximum number of sessions is 2048.
102 * Chained mbufs are supported only for source mbuf (destination must be
103   contiguous).
104 * Hash only is not supported for GCM and GMAC.
105 * Cipher only is not supported for GCM and GMAC.