15630257fSFerruh Yigit.. SPDX-License-Identifier: BSD-3-Clause 2*bf6eb2c2SPablo de Lara Copyright(c) 2016-2019 Intel Corporation. 32773c86dSPablo de Lara 42773c86dSPablo de LaraKASUMI Crypto Poll Mode Driver 52773c86dSPablo de Lara=============================== 62773c86dSPablo de Lara 7*bf6eb2c2SPablo de LaraThe KASUMI PMD (**librte_pmd_kasumi**) provides poll mode crypto driver support for 8*bf6eb2c2SPablo de Larautilizing `Intel IPSec Multi-buffer library <https://github.com/01org/intel-ipsec-mb>`_ 9*bf6eb2c2SPablo de Larawhich implements F8 and F9 functions for KASUMI UEA1 cipher and UIA1 hash algorithms. 102773c86dSPablo de Lara 112773c86dSPablo de LaraFeatures 122773c86dSPablo de Lara-------- 132773c86dSPablo de Lara 142773c86dSPablo de LaraKASUMI PMD has support for: 152773c86dSPablo de Lara 162773c86dSPablo de LaraCipher algorithm: 172773c86dSPablo de Lara 18fddf3804SDeepak Kumar Jain* RTE_CRYPTO_CIPHER_KASUMI_F8 192773c86dSPablo de Lara 202773c86dSPablo de LaraAuthentication algorithm: 212773c86dSPablo de Lara 22fddf3804SDeepak Kumar Jain* RTE_CRYPTO_AUTH_KASUMI_F9 232773c86dSPablo de Lara 242773c86dSPablo de LaraLimitations 252773c86dSPablo de Lara----------- 262773c86dSPablo de Lara 272773c86dSPablo de Lara* Chained mbufs are not supported. 289333cfbaSPablo de Lara* KASUMI(F9) supported only if hash offset and length field is byte-aligned. 29ebee5594SPablo de Lara* In-place bit-level operations for KASUMI(F8) are not supported 30ebee5594SPablo de Lara (if length and/or offset of data to be ciphered is not byte-aligned). 31ebee5594SPablo de Lara 322773c86dSPablo de Lara 332773c86dSPablo de LaraInstallation 342773c86dSPablo de Lara------------ 352773c86dSPablo de Lara 36*bf6eb2c2SPablo de LaraTo build DPDK with the KASUMI_PMD the user is required to download the multi-buffer 37*bf6eb2c2SPablo de Laralibrary from `here <https://github.com/01org/intel-ipsec-mb>`_ 38*bf6eb2c2SPablo de Laraand compile it on their user system before building DPDK. 39*bf6eb2c2SPablo de LaraThe latest version of the library supported by this PMD is v0.53, which 40*bf6eb2c2SPablo de Laracan be downloaded from `<https://github.com/01org/intel-ipsec-mb/archive/v0.53.zip>`_. 41*bf6eb2c2SPablo de Lara 422773c86dSPablo de LaraAfter downloading the library, the user needs to unpack and compile it 43*bf6eb2c2SPablo de Laraon their system before building DPDK: 44*bf6eb2c2SPablo de Lara 45*bf6eb2c2SPablo de Lara.. code-block:: console 462773c86dSPablo de Lara 47ae688ed8SPablo de Lara make 48*bf6eb2c2SPablo de Lara make install 49ae688ed8SPablo de Lara 50*bf6eb2c2SPablo de LaraAs a reference, the following table shows a mapping between the past DPDK versions 51*bf6eb2c2SPablo de Laraand the external crypto libraries supported by them: 524792d3eaSPablo de Lara 53*bf6eb2c2SPablo de Lara.. _table_kasumi_versions: 544792d3eaSPablo de Lara 55*bf6eb2c2SPablo de Lara.. table:: DPDK and external crypto library version compatibility 56ae688ed8SPablo de Lara 57*bf6eb2c2SPablo de Lara ============= ================================ 58*bf6eb2c2SPablo de Lara DPDK version Crypto library version 59*bf6eb2c2SPablo de Lara ============= ================================ 60*bf6eb2c2SPablo de Lara 16.11 - 19.11 LibSSO KASUMI 61*bf6eb2c2SPablo de Lara 20.02+ Multi-buffer library 0.53 62*bf6eb2c2SPablo de Lara ============= ================================ 63ae688ed8SPablo de Lara 642773c86dSPablo de Lara 652773c86dSPablo de LaraInitialization 662773c86dSPablo de Lara-------------- 672773c86dSPablo de Lara 682773c86dSPablo de LaraIn order to enable this virtual crypto PMD, user must: 692773c86dSPablo de Lara 70*bf6eb2c2SPablo de Lara* Build the multi buffer library (explained in Installation section). 712773c86dSPablo de Lara 72*bf6eb2c2SPablo de Lara* Build DPDK as follows: 732773c86dSPablo de Lara 74*bf6eb2c2SPablo de Lara.. code-block:: console 75*bf6eb2c2SPablo de Lara 76*bf6eb2c2SPablo de Lara make config T=x86_64-native-linux-gcc 77*bf6eb2c2SPablo de Lara sed -i 's,\(CONFIG_RTE_LIBRTE_PMD_KASUMI\)=n,\1=y,' build/.config 78*bf6eb2c2SPablo de Lara make 79*bf6eb2c2SPablo de Lara 802773c86dSPablo de Lara 812773c86dSPablo de LaraTo use the PMD in an application, user must: 822773c86dSPablo de Lara 832f6fec53SThomas Monjalon* Call rte_vdev_init("crypto_kasumi") within the application. 842773c86dSPablo de Lara 852f6fec53SThomas Monjalon* Use --vdev="crypto_kasumi" in the EAL options, which will call rte_vdev_init() internally. 862773c86dSPablo de Lara 872773c86dSPablo de LaraThe following parameters (all optional) can be provided in the previous two calls: 882773c86dSPablo de Lara 892773c86dSPablo de Lara* socket_id: Specify the socket where the memory for the device is going to be allocated 902773c86dSPablo de Lara (by default, socket_id will be the socket where the core that is creating the PMD is running on). 912773c86dSPablo de Lara 922773c86dSPablo de Lara* max_nb_queue_pairs: Specify the maximum number of queue pairs in the device (8 by default). 932773c86dSPablo de Lara 942773c86dSPablo de Lara* max_nb_sessions: Specify the maximum number of sessions that can be created (2048 by default). 952773c86dSPablo de Lara 962773c86dSPablo de LaraExample: 972773c86dSPablo de Lara 982773c86dSPablo de Lara.. code-block:: console 992773c86dSPablo de Lara 100fda78c51SPablo de Lara ./l2fwd-crypto -l 1 -n 4 --vdev="crypto_kasumi,socket_id=0,max_nb_sessions=128" \ 101fda78c51SPablo de Lara -- -p 1 --cdev SW --chain CIPHER_ONLY --cipher_algo "kasumi-f8" 1029333cfbaSPablo de Lara 1039333cfbaSPablo de LaraExtra notes on KASUMI F9 1049333cfbaSPablo de Lara------------------------ 1059333cfbaSPablo de Lara 1069333cfbaSPablo de LaraWhen using KASUMI F9 authentication algorithm, the input buffer must be 1079333cfbaSPablo de Laraconstructed according to the 3GPP KASUMI specifications (section 4.4, page 13): 1089333cfbaSPablo de Lara`<http://cryptome.org/3gpp/35201-900.pdf>`_. 1099333cfbaSPablo de LaraInput buffer has to have COUNT (4 bytes), FRESH (4 bytes), MESSAGE and DIRECTION (1 bit) 1109333cfbaSPablo de Laraconcatenated. After the DIRECTION bit, a single '1' bit is appended, followed by 1119333cfbaSPablo de Larabetween 0 and 7 '0' bits, so that the total length of the buffer is multiple of 8 bits. 1129333cfbaSPablo de LaraNote that the actual message can be any length, specified in bits. 1139333cfbaSPablo de Lara 1149333cfbaSPablo de LaraOnce this buffer is passed this way, when creating the crypto operation, 1159333cfbaSPablo de Laralength of data to authenticate (op.sym.auth.data.length) must be the length 1169333cfbaSPablo de Laraof all the items described above, including the padding at the end. 1179333cfbaSPablo de LaraAlso, offset of data to authenticate (op.sym.auth.data.offset) 1189333cfbaSPablo de Laramust be such that points at the start of the COUNT bytes. 119