build: use static deps for pkg-config libs.private
[dpdk.git] / lib / librte_security / rte_security.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright 2017 NXP.
3  * Copyright(c) 2017 Intel Corporation.
4  */
5
6 #ifndef _RTE_SECURITY_H_
7 #define _RTE_SECURITY_H_
8
9 /**
10  * @file rte_security.h
11  *
12  * RTE Security Common Definitions
13  *
14  */
15
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19
20 #include <sys/types.h>
21
22 #include <netinet/in.h>
23 #include <netinet/ip.h>
24 #include <netinet/ip6.h>
25
26 #include <rte_compat.h>
27 #include <rte_common.h>
28 #include <rte_crypto.h>
29 #include <rte_mbuf.h>
30 #include <rte_memory.h>
31 #include <rte_mempool.h>
32
33 /** IPSec protocol mode */
34 enum rte_security_ipsec_sa_mode {
35         RTE_SECURITY_IPSEC_SA_MODE_TRANSPORT = 1,
36         /**< IPSec Transport mode */
37         RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
38         /**< IPSec Tunnel mode */
39 };
40
41 /** IPSec Protocol */
42 enum rte_security_ipsec_sa_protocol {
43         RTE_SECURITY_IPSEC_SA_PROTO_AH = 1,
44         /**< AH protocol */
45         RTE_SECURITY_IPSEC_SA_PROTO_ESP,
46         /**< ESP protocol */
47 };
48
49 /** IPSEC tunnel type */
50 enum rte_security_ipsec_tunnel_type {
51         RTE_SECURITY_IPSEC_TUNNEL_IPV4 = 1,
52         /**< Outer header is IPv4 */
53         RTE_SECURITY_IPSEC_TUNNEL_IPV6,
54         /**< Outer header is IPv6 */
55 };
56
57 /**
58  * Security context for crypto/eth devices
59  *
60  * Security instance for each driver to register security operations.
61  * The application can get the security context from the crypto/eth device id
62  * using the APIs rte_cryptodev_get_sec_ctx()/rte_eth_dev_get_sec_ctx()
63  * This structure is used to identify the device(crypto/eth) for which the
64  * security operations need to be performed.
65  */
66 struct rte_security_ctx {
67         void *device;
68         /**< Crypto/ethernet device attached */
69         const struct rte_security_ops *ops;
70         /**< Pointer to security ops for the device */
71         uint16_t sess_cnt;
72         /**< Number of sessions attached to this context */
73 };
74
75 /**
76  * IPSEC tunnel parameters
77  *
78  * These parameters are used to build outbound tunnel headers.
79  */
80 struct rte_security_ipsec_tunnel_param {
81         enum rte_security_ipsec_tunnel_type type;
82         /**< Tunnel type: IPv4 or IPv6 */
83         RTE_STD_C11
84         union {
85                 struct {
86                         struct in_addr src_ip;
87                         /**< IPv4 source address */
88                         struct in_addr dst_ip;
89                         /**< IPv4 destination address */
90                         uint8_t dscp;
91                         /**< IPv4 Differentiated Services Code Point */
92                         uint8_t df;
93                         /**< IPv4 Don't Fragment bit */
94                         uint8_t ttl;
95                         /**< IPv4 Time To Live */
96                 } ipv4;
97                 /**< IPv4 header parameters */
98                 struct {
99                         struct in6_addr src_addr;
100                         /**< IPv6 source address */
101                         struct in6_addr dst_addr;
102                         /**< IPv6 destination address */
103                         uint8_t dscp;
104                         /**< IPv6 Differentiated Services Code Point */
105                         uint32_t flabel;
106                         /**< IPv6 flow label */
107                         uint8_t hlimit;
108                         /**< IPv6 hop limit */
109                 } ipv6;
110                 /**< IPv6 header parameters */
111         };
112 };
113
114 /**
115  * IPsec Security Association option flags
116  */
117 struct rte_security_ipsec_sa_options {
118         /**< Extended Sequence Numbers (ESN)
119          *
120          * * 1: Use extended (64 bit) sequence numbers
121          * * 0: Use normal sequence numbers
122          */
123         uint32_t esn : 1;
124
125         /**< UDP encapsulation
126          *
127          * * 1: Do UDP encapsulation/decapsulation so that IPSEC packets can
128          *      traverse through NAT boxes.
129          * * 0: No UDP encapsulation
130          */
131         uint32_t udp_encap : 1;
132
133         /**< Copy DSCP bits
134          *
135          * * 1: Copy IPv4 or IPv6 DSCP bits from inner IP header to
136          *      the outer IP header in encapsulation, and vice versa in
137          *      decapsulation.
138          * * 0: Do not change DSCP field.
139          */
140         uint32_t copy_dscp : 1;
141
142         /**< Copy IPv6 Flow Label
143          *
144          * * 1: Copy IPv6 flow label from inner IPv6 header to the
145          *      outer IPv6 header.
146          * * 0: Outer header is not modified.
147          */
148         uint32_t copy_flabel : 1;
149
150         /**< Copy IPv4 Don't Fragment bit
151          *
152          * * 1: Copy the DF bit from the inner IPv4 header to the outer
153          *      IPv4 header.
154          * * 0: Outer header is not modified.
155          */
156         uint32_t copy_df : 1;
157
158         /**< Decrement inner packet Time To Live (TTL) field
159          *
160          * * 1: In tunnel mode, decrement inner packet IPv4 TTL or
161          *      IPv6 Hop Limit after tunnel decapsulation, or before tunnel
162          *      encapsulation.
163          * * 0: Inner packet is not modified.
164          */
165         uint32_t dec_ttl : 1;
166 };
167
168 /** IPSec security association direction */
169 enum rte_security_ipsec_sa_direction {
170         RTE_SECURITY_IPSEC_SA_DIR_EGRESS,
171         /**< Encrypt and generate digest */
172         RTE_SECURITY_IPSEC_SA_DIR_INGRESS,
173         /**< Verify digest and decrypt */
174 };
175
176 /**
177  * IPsec security association configuration data.
178  *
179  * This structure contains data required to create an IPsec SA security session.
180  */
181 struct rte_security_ipsec_xform {
182         uint32_t spi;
183         /**< SA security parameter index */
184         uint32_t salt;
185         /**< SA salt */
186         struct rte_security_ipsec_sa_options options;
187         /**< various SA options */
188         enum rte_security_ipsec_sa_direction direction;
189         /**< IPSec SA Direction - Egress/Ingress */
190         enum rte_security_ipsec_sa_protocol proto;
191         /**< IPsec SA Protocol - AH/ESP */
192         enum rte_security_ipsec_sa_mode mode;
193         /**< IPsec SA Mode - transport/tunnel */
194         struct rte_security_ipsec_tunnel_param tunnel;
195         /**< Tunnel parameters, NULL for transport mode */
196         uint64_t esn_soft_limit;
197         /**< ESN for which the overflow event need to be raised */
198 };
199
200 /**
201  * MACsec security session configuration
202  */
203 struct rte_security_macsec_xform {
204         /** To be Filled */
205         int dummy;
206 };
207
208 /**
209  * PDCP Mode of session
210  */
211 enum rte_security_pdcp_domain {
212         RTE_SECURITY_PDCP_MODE_CONTROL, /**< PDCP control plane */
213         RTE_SECURITY_PDCP_MODE_DATA,    /**< PDCP data plane */
214 };
215
216 /** PDCP Frame direction */
217 enum rte_security_pdcp_direction {
218         RTE_SECURITY_PDCP_UPLINK,       /**< Uplink */
219         RTE_SECURITY_PDCP_DOWNLINK,     /**< Downlink */
220 };
221
222 /** PDCP Sequence Number Size selectors */
223 enum rte_security_pdcp_sn_size {
224         /** PDCP_SN_SIZE_5: 5bit sequence number */
225         RTE_SECURITY_PDCP_SN_SIZE_5 = 5,
226         /** PDCP_SN_SIZE_7: 7bit sequence number */
227         RTE_SECURITY_PDCP_SN_SIZE_7 = 7,
228         /** PDCP_SN_SIZE_12: 12bit sequence number */
229         RTE_SECURITY_PDCP_SN_SIZE_12 = 12,
230         /** PDCP_SN_SIZE_15: 15bit sequence number */
231         RTE_SECURITY_PDCP_SN_SIZE_15 = 15,
232         /** PDCP_SN_SIZE_18: 18bit sequence number */
233         RTE_SECURITY_PDCP_SN_SIZE_18 = 18
234 };
235
236 /**
237  * PDCP security association configuration data.
238  *
239  * This structure contains data required to create a PDCP security session.
240  */
241 struct rte_security_pdcp_xform {
242         int8_t bearer;  /**< PDCP bearer ID */
243         /** Enable in order delivery, this field shall be set only if
244          * driver/HW is capable. See RTE_SECURITY_PDCP_ORDERING_CAP.
245          */
246         uint8_t en_ordering;
247         /** Notify driver/HW to detect and remove duplicate packets.
248          * This field should be set only when driver/hw is capable.
249          * See RTE_SECURITY_PDCP_DUP_DETECT_CAP.
250          */
251         uint8_t remove_duplicates;
252         /** PDCP mode of operation: Control or data */
253         enum rte_security_pdcp_domain domain;
254         /** PDCP Frame Direction 0:UL 1:DL */
255         enum rte_security_pdcp_direction pkt_dir;
256         /** Sequence number size, 5/7/12/15/18 */
257         enum rte_security_pdcp_sn_size sn_size;
258         /** Starting Hyper Frame Number to be used together with the SN
259          * from the PDCP frames
260          */
261         uint32_t hfn;
262         /** HFN Threshold for key renegotiation */
263         uint32_t hfn_threshold;
264 };
265
266 /**
267  * Security session action type.
268  */
269 enum rte_security_session_action_type {
270         RTE_SECURITY_ACTION_TYPE_NONE,
271         /**< No security actions */
272         RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO,
273         /**< Crypto processing for security protocol is processed inline
274          * during transmission
275          */
276         RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL,
277         /**< All security protocol processing is performed inline during
278          * transmission
279          */
280         RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
281         /**< All security protocol processing including crypto is performed
282          * on a lookaside accelerator
283          */
284 };
285
286 /** Security session protocol definition */
287 enum rte_security_session_protocol {
288         RTE_SECURITY_PROTOCOL_IPSEC = 1,
289         /**< IPsec Protocol */
290         RTE_SECURITY_PROTOCOL_MACSEC,
291         /**< MACSec Protocol */
292         RTE_SECURITY_PROTOCOL_PDCP,
293         /**< PDCP Protocol */
294 };
295
296 /**
297  * Security session configuration
298  */
299 struct rte_security_session_conf {
300         enum rte_security_session_action_type action_type;
301         /**< Type of action to be performed on the session */
302         enum rte_security_session_protocol protocol;
303         /**< Security protocol to be configured */
304         RTE_STD_C11
305         union {
306                 struct rte_security_ipsec_xform ipsec;
307                 struct rte_security_macsec_xform macsec;
308                 struct rte_security_pdcp_xform pdcp;
309         };
310         /**< Configuration parameters for security session */
311         struct rte_crypto_sym_xform *crypto_xform;
312         /**< Security Session Crypto Transformations */
313         void *userdata;
314         /**< Application specific userdata to be saved with session */
315 };
316
317 struct rte_security_session {
318         void *sess_private_data;
319         /**< Private session material */
320         uint64_t opaque_data;
321         /**< Opaque user defined data */
322 };
323
324 /**
325  * Create security session as specified by the session configuration
326  *
327  * @param   instance    security instance
328  * @param   conf        session configuration parameters
329  * @param   mp          mempool to allocate session objects from
330  * @return
331  *  - On success, pointer to session
332  *  - On failure, NULL
333  */
334 struct rte_security_session *
335 rte_security_session_create(struct rte_security_ctx *instance,
336                             struct rte_security_session_conf *conf,
337                             struct rte_mempool *mp);
338
339 /**
340  * Update security session as specified by the session configuration
341  *
342  * @param   instance    security instance
343  * @param   sess        session to update parameters
344  * @param   conf        update configuration parameters
345  * @return
346  *  - On success returns 0
347  *  - On failure return errno
348  */
349 int __rte_experimental
350 rte_security_session_update(struct rte_security_ctx *instance,
351                             struct rte_security_session *sess,
352                             struct rte_security_session_conf *conf);
353
354 /**
355  * Get the size of the security session data for a device.
356  *
357  * @param   instance    security instance.
358  *
359  * @return
360  *   - Size of the private data, if successful
361  *   - 0 if device is invalid or does not support the operation.
362  */
363 unsigned int
364 rte_security_session_get_size(struct rte_security_ctx *instance);
365
366 /**
367  * Free security session header and the session private data and
368  * return it to its original mempool.
369  *
370  * @param   instance    security instance
371  * @param   sess        security session to freed
372  *
373  * @return
374  *  - 0 if successful.
375  *  - -EINVAL if session is NULL.
376  *  - -EBUSY if not all device private data has been freed.
377  */
378 int
379 rte_security_session_destroy(struct rte_security_ctx *instance,
380                              struct rte_security_session *sess);
381
382 /**
383  *  Updates the buffer with device-specific defined metadata
384  *
385  * @param       instance        security instance
386  * @param       sess            security session
387  * @param       mb              packet mbuf to set metadata on.
388  * @param       params          device-specific defined parameters
389  *                              required for metadata
390  *
391  * @return
392  *  - On success, zero.
393  *  - On failure, a negative value.
394  */
395 int
396 rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
397                               struct rte_security_session *sess,
398                               struct rte_mbuf *mb, void *params);
399
400 /**
401  * Get userdata associated with the security session. Device specific metadata
402  * provided would be used to uniquely identify the security session being
403  * referred to. This userdata would be registered while creating the session,
404  * and application can use this to identify the SA etc.
405  *
406  * Device specific metadata would be set in mbuf for inline processed inbound
407  * packets. In addition, the same metadata would be set for IPsec events
408  * reported by rte_eth_event framework.
409  *
410  * @param   instance    security instance
411  * @param   md          device-specific metadata
412  *
413  * @return
414  *  - On success, userdata
415  *  - On failure, NULL
416  */
417 void * __rte_experimental
418 rte_security_get_userdata(struct rte_security_ctx *instance, uint64_t md);
419
420 /**
421  * Attach a session to a symmetric crypto operation
422  *
423  * @param       sym_op  crypto operation
424  * @param       sess    security session
425  */
426 static inline int
427 __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
428                               struct rte_security_session *sess)
429 {
430         sym_op->sec_session = sess;
431
432         return 0;
433 }
434
435 static inline void *
436 get_sec_session_private_data(const struct rte_security_session *sess)
437 {
438         return sess->sess_private_data;
439 }
440
441 static inline void
442 set_sec_session_private_data(struct rte_security_session *sess,
443                              void *private_data)
444 {
445         sess->sess_private_data = private_data;
446 }
447
448 /**
449  * Attach a session to a crypto operation.
450  * This API is needed only in case of RTE_SECURITY_SESS_CRYPTO_PROTO_OFFLOAD
451  * For other rte_security_session_action_type, ol_flags in rte_mbuf may be
452  * defined to perform security operations.
453  *
454  * @param       op      crypto operation
455  * @param       sess    security session
456  */
457 static inline int
458 rte_security_attach_session(struct rte_crypto_op *op,
459                             struct rte_security_session *sess)
460 {
461         if (unlikely(op->type != RTE_CRYPTO_OP_TYPE_SYMMETRIC))
462                 return -EINVAL;
463
464         op->sess_type =  RTE_CRYPTO_OP_SECURITY_SESSION;
465
466         return __rte_security_attach_session(op->sym, sess);
467 }
468
469 struct rte_security_macsec_stats {
470         uint64_t reserved;
471 };
472
473 struct rte_security_ipsec_stats {
474         uint64_t reserved;
475
476 };
477
478 struct rte_security_pdcp_stats {
479         uint64_t reserved;
480 };
481
482 struct rte_security_stats {
483         enum rte_security_session_protocol protocol;
484         /**< Security protocol to be configured */
485
486         RTE_STD_C11
487         union {
488                 struct rte_security_macsec_stats macsec;
489                 struct rte_security_ipsec_stats ipsec;
490                 struct rte_security_pdcp_stats pdcp;
491         };
492 };
493
494 /**
495  * Get security session statistics
496  *
497  * @param       instance        security instance
498  * @param       sess            security session
499  * @param       stats           statistics
500  * @return
501  *  - On success return 0
502  *  - On failure errno
503  */
504 int __rte_experimental
505 rte_security_session_stats_get(struct rte_security_ctx *instance,
506                                struct rte_security_session *sess,
507                                struct rte_security_stats *stats);
508
509 /**
510  * Security capability definition
511  */
512 struct rte_security_capability {
513         enum rte_security_session_action_type action;
514         /**< Security action type*/
515         enum rte_security_session_protocol protocol;
516         /**< Security protocol */
517         RTE_STD_C11
518         union {
519                 struct {
520                         enum rte_security_ipsec_sa_protocol proto;
521                         /**< IPsec SA protocol */
522                         enum rte_security_ipsec_sa_mode mode;
523                         /**< IPsec SA mode */
524                         enum rte_security_ipsec_sa_direction direction;
525                         /**< IPsec SA direction */
526                         struct rte_security_ipsec_sa_options options;
527                         /**< IPsec SA supported options */
528                 } ipsec;
529                 /**< IPsec capability */
530                 struct {
531                         /* To be Filled */
532                         int dummy;
533                 } macsec;
534                 /**< MACsec capability */
535                 struct {
536                         enum rte_security_pdcp_domain domain;
537                         /**< PDCP mode of operation: Control or data */
538                         uint32_t capa_flags;
539                         /**< Capabilitity flags, see RTE_SECURITY_PDCP_* */
540                 } pdcp;
541                 /**< PDCP capability */
542         };
543
544         const struct rte_cryptodev_capabilities *crypto_capabilities;
545         /**< Corresponding crypto capabilities for security capability  */
546
547         uint32_t ol_flags;
548         /**< Device offload flags */
549 };
550
551 /** Underlying Hardware/driver which support PDCP may or may not support
552  * packet ordering. Set RTE_SECURITY_PDCP_ORDERING_CAP if it support.
553  * If it is not set, driver/HW assumes packets received are in order
554  * and it will be application's responsibility to maintain ordering.
555  */
556 #define RTE_SECURITY_PDCP_ORDERING_CAP          0x00000001
557
558 /** Underlying Hardware/driver which support PDCP may or may not detect
559  * duplicate packet. Set RTE_SECURITY_PDCP_DUP_DETECT_CAP if it support.
560  * If it is not set, driver/HW assumes there is no duplicate packet received.
561  */
562 #define RTE_SECURITY_PDCP_DUP_DETECT_CAP        0x00000002
563
564 #define RTE_SECURITY_TX_OLOAD_NEED_MDATA        0x00000001
565 /**< HW needs metadata update, see rte_security_set_pkt_metadata().
566  */
567
568 #define RTE_SECURITY_TX_HW_TRAILER_OFFLOAD      0x00000002
569 /**< HW constructs trailer of packets
570  * Transmitted packets will have the trailer added to them
571  * by hardawre. The next protocol field will be based on
572  * the mbuf->inner_esp_next_proto field.
573  */
574 #define RTE_SECURITY_RX_HW_TRAILER_OFFLOAD      0x00010000
575 /**< HW removes trailer of packets
576  * Received packets have no trailer, the next protocol field
577  * is supplied in the mbuf->inner_esp_next_proto field.
578  * Inner packet is not modified.
579  */
580
581 /**
582  * Security capability index used to query a security instance for a specific
583  * security capability
584  */
585 struct rte_security_capability_idx {
586         enum rte_security_session_action_type action;
587         enum rte_security_session_protocol protocol;
588
589         RTE_STD_C11
590         union {
591                 struct {
592                         enum rte_security_ipsec_sa_protocol proto;
593                         enum rte_security_ipsec_sa_mode mode;
594                         enum rte_security_ipsec_sa_direction direction;
595                 } ipsec;
596                 struct {
597                         enum rte_security_pdcp_domain domain;
598                         uint32_t capa_flags;
599                 } pdcp;
600         };
601 };
602
603 /**
604  *  Returns array of security instance capabilities
605  *
606  * @param       instance        Security instance.
607  *
608  * @return
609  *   - Returns array of security capabilities.
610  *   - Return NULL if no capabilities available.
611  */
612 const struct rte_security_capability *
613 rte_security_capabilities_get(struct rte_security_ctx *instance);
614
615 /**
616  * Query if a specific capability is available on security instance
617  *
618  * @param       instance        security instance.
619  * @param       idx             security capability index to match against
620  *
621  * @return
622  *   - Returns pointer to security capability on match of capability
623  *     index criteria.
624  *   - Return NULL if the capability not matched on security instance.
625  */
626 const struct rte_security_capability *
627 rte_security_capability_get(struct rte_security_ctx *instance,
628                             struct rte_security_capability_idx *idx);
629
630 #ifdef __cplusplus
631 }
632 #endif
633
634 #endif /* _RTE_SECURITY_H_ */