security: introduce security API and framework
[dpdk.git] / lib / librte_security / rte_security.h
1 /*-
2  *   BSD LICENSE
3  *
4  *   Copyright 2017 NXP.
5  *   Copyright(c) 2017 Intel Corporation. All rights reserved.
6  *
7  *   Redistribution and use in source and binary forms, with or without
8  *   modification, are permitted provided that the following conditions
9  *   are met:
10  *
11  *     * Redistributions of source code must retain the above copyright
12  *       notice, this list of conditions and the following disclaimer.
13  *     * Redistributions in binary form must reproduce the above copyright
14  *       notice, this list of conditions and the following disclaimer in
15  *       the documentation and/or other materials provided with the
16  *       distribution.
17  *     * Neither the name of NXP nor the names of its
18  *       contributors may be used to endorse or promote products derived
19  *       from this software without specific prior written permission.
20  *
21  *   THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
22  *   "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
23  *   LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
24  *   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
25  *   OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
26  *   SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
27  *   LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
28  *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
29  *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
30  *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
31  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32  */
33
34 #ifndef _RTE_SECURITY_H_
35 #define _RTE_SECURITY_H_
36
37 /**
38  * @file rte_security.h
39  * @b EXPERIMENTAL: this API may change without prior notice
40  *
41  * RTE Security Common Definitions
42  *
43  */
44
45 #ifdef __cplusplus
46 extern "C" {
47 #endif
48
49 #include <sys/types.h>
50
51 #include <netinet/in.h>
52 #include <netinet/ip.h>
53 #include <netinet/ip6.h>
54
55 #include <rte_common.h>
56 #include <rte_crypto.h>
57 #include <rte_mbuf.h>
58 #include <rte_memory.h>
59 #include <rte_mempool.h>
60
61 /** IPSec protocol mode */
62 enum rte_security_ipsec_sa_mode {
63         RTE_SECURITY_IPSEC_SA_MODE_TRANSPORT,
64         /**< IPSec Transport mode */
65         RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
66         /**< IPSec Tunnel mode */
67 };
68
69 /** IPSec Protocol */
70 enum rte_security_ipsec_sa_protocol {
71         RTE_SECURITY_IPSEC_SA_PROTO_AH,
72         /**< AH protocol */
73         RTE_SECURITY_IPSEC_SA_PROTO_ESP,
74         /**< ESP protocol */
75 };
76
77 /** IPSEC tunnel type */
78 enum rte_security_ipsec_tunnel_type {
79         RTE_SECURITY_IPSEC_TUNNEL_IPV4,
80         /**< Outer header is IPv4 */
81         RTE_SECURITY_IPSEC_TUNNEL_IPV6,
82         /**< Outer header is IPv6 */
83 };
84
85 /**
86  * Security context for crypto/eth devices
87  *
88  * Security instance for each driver to register security operations.
89  * The application can get the security context from the crypto/eth device id
90  * using the APIs rte_cryptodev_get_sec_ctx()/rte_eth_dev_get_sec_ctx()
91  * This structure is used to identify the device(crypto/eth) for which the
92  * security operations need to be performed.
93  */
94 struct rte_security_ctx {
95         void *device;
96         /**< Crypto/ethernet device attached */
97         struct rte_security_ops *ops;
98         /**< Pointer to security ops for the device */
99         uint16_t sess_cnt;
100         /**< Number of sessions attached to this context */
101 };
102
103 /**
104  * IPSEC tunnel parameters
105  *
106  * These parameters are used to build outbound tunnel headers.
107  */
108 struct rte_security_ipsec_tunnel_param {
109         enum rte_security_ipsec_tunnel_type type;
110         /**< Tunnel type: IPv4 or IPv6 */
111         RTE_STD_C11
112         union {
113                 struct {
114                         struct in_addr src_ip;
115                         /**< IPv4 source address */
116                         struct in_addr dst_ip;
117                         /**< IPv4 destination address */
118                         uint8_t dscp;
119                         /**< IPv4 Differentiated Services Code Point */
120                         uint8_t df;
121                         /**< IPv4 Don't Fragment bit */
122                         uint8_t ttl;
123                         /**< IPv4 Time To Live */
124                 } ipv4;
125                 /**< IPv4 header parameters */
126                 struct {
127                         struct in6_addr src_addr;
128                         /**< IPv6 source address */
129                         struct in6_addr dst_addr;
130                         /**< IPv6 destination address */
131                         uint8_t dscp;
132                         /**< IPv6 Differentiated Services Code Point */
133                         uint32_t flabel;
134                         /**< IPv6 flow label */
135                         uint8_t hlimit;
136                         /**< IPv6 hop limit */
137                 } ipv6;
138                 /**< IPv6 header parameters */
139         };
140 };
141
142 /**
143  * IPsec Security Association option flags
144  */
145 struct rte_security_ipsec_sa_options {
146         /**< Extended Sequence Numbers (ESN)
147          *
148          * * 1: Use extended (64 bit) sequence numbers
149          * * 0: Use normal sequence numbers
150          */
151         uint32_t esn : 1;
152
153         /**< UDP encapsulation
154          *
155          * * 1: Do UDP encapsulation/decapsulation so that IPSEC packets can
156          *      traverse through NAT boxes.
157          * * 0: No UDP encapsulation
158          */
159         uint32_t udp_encap : 1;
160
161         /**< Copy DSCP bits
162          *
163          * * 1: Copy IPv4 or IPv6 DSCP bits from inner IP header to
164          *      the outer IP header in encapsulation, and vice versa in
165          *      decapsulation.
166          * * 0: Do not change DSCP field.
167          */
168         uint32_t copy_dscp : 1;
169
170         /**< Copy IPv6 Flow Label
171          *
172          * * 1: Copy IPv6 flow label from inner IPv6 header to the
173          *      outer IPv6 header.
174          * * 0: Outer header is not modified.
175          */
176         uint32_t copy_flabel : 1;
177
178         /**< Copy IPv4 Don't Fragment bit
179          *
180          * * 1: Copy the DF bit from the inner IPv4 header to the outer
181          *      IPv4 header.
182          * * 0: Outer header is not modified.
183          */
184         uint32_t copy_df : 1;
185
186         /**< Decrement inner packet Time To Live (TTL) field
187          *
188          * * 1: In tunnel mode, decrement inner packet IPv4 TTL or
189          *      IPv6 Hop Limit after tunnel decapsulation, or before tunnel
190          *      encapsulation.
191          * * 0: Inner packet is not modified.
192          */
193         uint32_t dec_ttl : 1;
194 };
195
196 /** IPSec security association direction */
197 enum rte_security_ipsec_sa_direction {
198         RTE_SECURITY_IPSEC_SA_DIR_EGRESS,
199         /**< Encrypt and generate digest */
200         RTE_SECURITY_IPSEC_SA_DIR_INGRESS,
201         /**< Verify digest and decrypt */
202 };
203
204 /**
205  * IPsec security association configuration data.
206  *
207  * This structure contains data required to create an IPsec SA security session.
208  */
209 struct rte_security_ipsec_xform {
210         uint32_t spi;
211         /**< SA security parameter index */
212         uint32_t salt;
213         /**< SA salt */
214         struct rte_security_ipsec_sa_options options;
215         /**< various SA options */
216         enum rte_security_ipsec_sa_direction direction;
217         /**< IPSec SA Direction - Egress/Ingress */
218         enum rte_security_ipsec_sa_protocol proto;
219         /**< IPsec SA Protocol - AH/ESP */
220         enum rte_security_ipsec_sa_mode mode;
221         /**< IPsec SA Mode - transport/tunnel */
222         struct rte_security_ipsec_tunnel_param tunnel;
223         /**< Tunnel parameters, NULL for transport mode */
224 };
225
226 /**
227  * MACsec security session configuration
228  */
229 struct rte_security_macsec_xform {
230         /** To be Filled */
231 };
232
233 /**
234  * Security session action type.
235  */
236 enum rte_security_session_action_type {
237         RTE_SECURITY_ACTION_TYPE_NONE,
238         /**< No security actions */
239         RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO,
240         /**< Crypto processing for security protocol is processed inline
241          * during transmission
242          */
243         RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL,
244         /**< All security protocol processing is performed inline during
245          * transmission
246          */
247         RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
248         /**< All security protocol processing including crypto is performed
249          * on a lookaside accelerator
250          */
251 };
252
253 /** Security session protocol definition */
254 enum rte_security_session_protocol {
255         RTE_SECURITY_PROTOCOL_IPSEC,
256         /**< IPsec Protocol */
257         RTE_SECURITY_PROTOCOL_MACSEC,
258         /**< MACSec Protocol */
259 };
260
261 /**
262  * Security session configuration
263  */
264 struct rte_security_session_conf {
265         enum rte_security_session_action_type action_type;
266         /**< Type of action to be performed on the session */
267         enum rte_security_session_protocol protocol;
268         /**< Security protocol to be configured */
269         union {
270                 struct rte_security_ipsec_xform ipsec;
271                 struct rte_security_macsec_xform macsec;
272         };
273         /**< Configuration parameters for security session */
274         struct rte_crypto_sym_xform *crypto_xform;
275         /**< Security Session Crypto Transformations */
276 };
277
278 struct rte_security_session {
279         void *sess_private_data;
280         /**< Private session material */
281 };
282
283 /**
284  * Create security session as specified by the session configuration
285  *
286  * @param   instance    security instance
287  * @param   conf        session configuration parameters
288  * @param   mp          mempool to allocate session objects from
289  * @return
290  *  - On success, pointer to session
291  *  - On failure, NULL
292  */
293 struct rte_security_session *
294 rte_security_session_create(struct rte_security_ctx *instance,
295                             struct rte_security_session_conf *conf,
296                             struct rte_mempool *mp);
297
298 /**
299  * Update security session as specified by the session configuration
300  *
301  * @param   instance    security instance
302  * @param   sess        session to update parameters
303  * @param   conf        update configuration parameters
304  * @return
305  *  - On success returns 0
306  *  - On failure return errno
307  */
308 int
309 rte_security_session_update(struct rte_security_ctx *instance,
310                             struct rte_security_session *sess,
311                             struct rte_security_session_conf *conf);
312
313 /**
314  * Free security session header and the session private data and
315  * return it to its original mempool.
316  *
317  * @param   instance    security instance
318  * @param   sess        security session to freed
319  *
320  * @return
321  *  - 0 if successful.
322  *  - -EINVAL if session is NULL.
323  *  - -EBUSY if not all device private data has been freed.
324  */
325 int
326 rte_security_session_destroy(struct rte_security_ctx *instance,
327                              struct rte_security_session *sess);
328
329 /**
330  *  Updates the buffer with device-specific defined metadata
331  *
332  * @param       instance        security instance
333  * @param       sess            security session
334  * @param       mb              packet mbuf to set metadata on.
335  * @param       params          device-specific defined parameters
336  *                              required for metadata
337  *
338  * @return
339  *  - On success, zero.
340  *  - On failure, a negative value.
341  */
342 int
343 rte_security_set_pkt_metadata(struct rte_security_ctx *instance,
344                               struct rte_security_session *sess,
345                               struct rte_mbuf *mb, void *params);
346
347 /**
348  * Attach a session to a symmetric crypto operation
349  *
350  * @param       sym_op  crypto operation
351  * @param       sess    security session
352  */
353 static inline int
354 __rte_security_attach_session(struct rte_crypto_sym_op *sym_op,
355                               struct rte_security_session *sess)
356 {
357         sym_op->sec_session = sess;
358
359         return 0;
360 }
361
362 static inline void *
363 get_sec_session_private_data(const struct rte_security_session *sess)
364 {
365         return sess->sess_private_data;
366 }
367
368 static inline void
369 set_sec_session_private_data(struct rte_security_session *sess,
370                              void *private_data)
371 {
372         sess->sess_private_data = private_data;
373 }
374
375 /**
376  * Attach a session to a crypto operation.
377  * This API is needed only in case of RTE_SECURITY_SESS_CRYPTO_PROTO_OFFLOAD
378  * For other rte_security_session_action_type, ol_flags in rte_mbuf may be
379  * defined to perform security operations.
380  *
381  * @param       op      crypto operation
382  * @param       sess    security session
383  */
384 static inline int
385 rte_security_attach_session(struct rte_crypto_op *op,
386                             struct rte_security_session *sess)
387 {
388         if (unlikely(op->type != RTE_CRYPTO_OP_TYPE_SYMMETRIC))
389                 return -EINVAL;
390
391         op->sess_type =  RTE_CRYPTO_OP_SECURITY_SESSION;
392
393         return __rte_security_attach_session(op->sym, sess);
394 }
395
396 struct rte_security_macsec_stats {
397         uint64_t reserved;
398 };
399
400 struct rte_security_ipsec_stats {
401         uint64_t reserved;
402
403 };
404
405 struct rte_security_stats {
406         enum rte_security_session_protocol protocol;
407         /**< Security protocol to be configured */
408
409         union {
410                 struct rte_security_macsec_stats macsec;
411                 struct rte_security_ipsec_stats ipsec;
412         };
413 };
414
415 /**
416  * Get security session statistics
417  *
418  * @param       instance        security instance
419  * @param       sess            security session
420  * @param       stats           statistics
421  * @return
422  *  - On success return 0
423  *  - On failure errno
424  */
425 int
426 rte_security_session_stats_get(struct rte_security_ctx *instance,
427                                struct rte_security_session *sess,
428                                struct rte_security_stats *stats);
429
430 /**
431  * Security capability definition
432  */
433 struct rte_security_capability {
434         enum rte_security_session_action_type action;
435         /**< Security action type*/
436         enum rte_security_session_protocol protocol;
437         /**< Security protocol */
438         RTE_STD_C11
439         union {
440                 struct {
441                         enum rte_security_ipsec_sa_protocol proto;
442                         /**< IPsec SA protocol */
443                         enum rte_security_ipsec_sa_mode mode;
444                         /**< IPsec SA mode */
445                         enum rte_security_ipsec_sa_direction direction;
446                         /**< IPsec SA direction */
447                         struct rte_security_ipsec_sa_options options;
448                         /**< IPsec SA supported options */
449                 } ipsec;
450                 /**< IPsec capability */
451                 struct {
452                         /* To be Filled */
453                 } macsec;
454                 /**< MACsec capability */
455         };
456
457         const struct rte_cryptodev_capabilities *crypto_capabilities;
458         /**< Corresponding crypto capabilities for security capability  */
459
460         uint32_t ol_flags;
461         /**< Device offload flags */
462 };
463
464 #define RTE_SECURITY_TX_OLOAD_NEED_MDATA        0x00000001
465 /**< HW needs metadata update, see rte_security_set_pkt_metadata().
466  */
467
468 #define RTE_SECURITY_TX_HW_TRAILER_OFFLOAD      0x00000002
469 /**< HW constructs trailer of packets
470  * Transmitted packets will have the trailer added to them
471  * by hardawre. The next protocol field will be based on
472  * the mbuf->inner_esp_next_proto field.
473  */
474 #define RTE_SECURITY_RX_HW_TRAILER_OFFLOAD      0x00010000
475 /**< HW removes trailer of packets
476  * Received packets have no trailer, the next protocol field
477  * is supplied in the mbuf->inner_esp_next_proto field.
478  * Inner packet is not modified.
479  */
480
481 /**
482  * Security capability index used to query a security instance for a specific
483  * security capability
484  */
485 struct rte_security_capability_idx {
486         enum rte_security_session_action_type action;
487         enum rte_security_session_protocol protocol;
488
489         union {
490                 struct {
491                         enum rte_security_ipsec_sa_protocol proto;
492                         enum rte_security_ipsec_sa_mode mode;
493                         enum rte_security_ipsec_sa_direction direction;
494                 } ipsec;
495         };
496 };
497
498 /**
499  *  Returns array of security instance capabilities
500  *
501  * @param       instance        Security instance.
502  *
503  * @return
504  *   - Returns array of security capabilities.
505  *   - Return NULL if no capabilities available.
506  */
507 const struct rte_security_capability *
508 rte_security_capabilities_get(struct rte_security_ctx *instance);
509
510 /**
511  * Query if a specific capability is available on security instance
512  *
513  * @param       instance        security instance.
514  * @param       idx             security capability index to match against
515  *
516  * @return
517  *   - Returns pointer to security capability on match of capability
518  *     index criteria.
519  *   - Return NULL if the capability not matched on security instance.
520  */
521 const struct rte_security_capability *
522 rte_security_capability_get(struct rte_security_ctx *instance,
523                             struct rte_security_capability_idx *idx);
524
525 #ifdef __cplusplus
526 }
527 #endif
528
529 #endif /* _RTE_SECURITY_H_ */