1 #ifndef _SALLD_H
2 #define _SALLD_H
4 /* ========================================================================== */
5 /**
6 * @file salld.h
7 *
8 * path ti/drv/sa/salld.h
9 *
10 * @brief SA LLD Interface Unit API and Data Definitions
11 *
12 * ============================================================================
13 * Copyright (c) Texas Instruments Incorporated 2009-2012
14 *
15 * Redistribution and use in source and binary forms, with or without
16 * modification, are permitted provided that the following conditions
17 * are met:
18 *
19 * Redistributions of source code must retain the above copyright
20 * notice, this list of conditions and the following disclaimer.
21 *
22 * Redistributions in binary form must reproduce the above copyright
23 * notice, this list of conditions and the following disclaimer in the
24 * documentation and/or other materials provided with the
25 * distribution.
26 *
27 * Neither the name of Texas Instruments Incorporated nor the names of
28 * its contributors may be used to endorse or promote products derived
29 * from this software without specific prior written permission.
30 *
31 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
32 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
33 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
34 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
35 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
36 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
37 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
38 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
39 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
40 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
41 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
42 *
43 */
45 /** @mainpage Security Accelerator Low Level Driver
46 *
47 * @section intro Introduction
48 *
49 * The Security Accelerator (SA) also known as cp_ace (Adaptive Cryptographic Engine) is designed to
50 * provide packet security as part of IPSEC, SRTP, and 3GPP industry standards. The security accelerator
51 * low level driver (referred to as the module) provides APIs for the configuration and control of
52 * the security accelerator sub-system. The SA low level driver provides an abstraction layer between
53 * the application and the Security Accelerator Sub System (SASS). It provides both the system level
54 * interface and the channel-level interface with a set of APIs defined here.
55 *
56 * The common interface maintains the system-level resources and needs to be coordinated among multiple
57 * CGEM cores. All the data access provided by the common interface will invoke the SA CSL layer.
58 * The common interface performs the following tasks:
59 * - Reset, download and update the SA PDSP images.
60 * - Query SA states and statistics.
61 * - Read a 64-bit true random number.
62 * - Perform the large integer arithmetic through the PKA module.
63 * - Monitor and report SA system errors.
64 *
65 * The channel interface performs protocol-specific pre-processing for all the packets to be passed to
66 * the SA and protocol-specific post-processing of all the packets received from the SA. The channel interface
67 * performs the following tasks:
68 * - Convert the channel configuration information into the security contexts defined by the SA.
69 * - Perform protocol-specific packet operations such as insertion of the ESP header, padding and ESP tail.
70 * - Decrypt and authenticate the received SRTP packet when the SA is not able to perform the operations
71 * due to the key validation failure.
72 * - Generate the SA operation control command labels in data mode operation.
73 * - Maintain the protocol-specific channel statistics.
74 *
75 * With the exception of some initial setup functions, the module does not communicate directly with
76 * the sub-system. The driver does not contain a transport layer and is always non-blocking. The
77 * software layers above the SA LLD must call the appropriate SA LLD APIs, and then call the appropriate
78 * PA and/or CPPI and QMSS APIs to actually send the data to the SA sub-system.
79 *
80 */
82 #ifdef __cplusplus
83 extern "C" {
84 #endif
86 /* System level header files */
87 #include <stdint.h>
88 #include <stdlib.h>
89 #include <string.h>
91 #include <ti/drv/sa/saver.h>
93 /* Define SALLD Module as a master group in Doxygen format and add all SA LLD API
94 definitions to this group. */
95 /** @defgroup salld_module SA LLD Module API
96 * @{
97 */
98 /** @} */
100 /** @defgroup salld_api_functions SA LLD Functions
101 * @ingroup salld_module
102 */
104 /** @defgroup salld_api_macros SA LLD Macros
105 * @ingroup salld_module
106 */
108 /** @defgroup salld_api_structures SA LLD Data Structures
109 * @ingroup salld_module
110 */
112 /** @defgroup salld_api_constants SA LLD Constants (enums and defines)
113 * @ingroup salld_module
114 */
117 /**
118 * @defgroup salldDebugMessageTypes SALLD Debug message types
119 * @ingroup salld_api_constants
120 * @{
121 *
122 * @name SALLD Debug message types
123 *
124 * Debug message types used by debugInfo().
125 */
126 /*@{*/
127 /**
128 * @def sa_DBG_INFORMATIONAL
129 * SALLD Debug Message Type -- SA LLD general debug information message.
130 */
131 #define sa_DBG_INFORMATIONAL 0
132 /**
133 * @def sa_DBG_WARNING
134 * SALLD Debug Message Type -- SA LLD warning debug information message.
135 */
136 #define sa_DBG_WARNING 1
138 /**
139 * @def sa_DBG_FATAL_ERROR
140 * SALLD Debug Message Type -- SA LLD critical debug information message.
141 */
142 #define sa_DBG_FATAL_ERROR 2
143 /*@}*/
144 /** @} */
146 /**
147 * @defgroup salldDebugMessageCodes SALLD Debug message codes
148 * @ingroup salld_api_constants
149 * @{
150 *
151 * @name SALLD Debug message codes
152 *
153 * Debug message codes used by debugInfo().
154 */
155 /*@{*/
156 /**
157 * @def sa_MSG_NO_MKI_LEN_CHANGE_ON_FLY
158 * SALLD Debug Message Code -- One-the-fly MKI change is not supported.
159 */
160 #define sa_MSG_NO_MKI_LEN_CHANGE_ON_FLY 1
161 /**
162 * @def sa_MSG_MKI_LEN_IS_ZERO
163 * SALLD Debug Message Code -- MKI length is zero.
164 */
165 #define sa_MSG_MKI_LEN_IS_ZERO 2
166 /*@}*/
167 /** @} */
169 /**
170 * @defgroup salldSubSysStates SALLD Sub-System Queries and States
171 * @ingroup salld_api_constants
172 * @{
173 *
174 * @name SALLD Sub-System Queries and States
175 *
176 * SA Sub-System reset state and query arguments used by API function @ref Sa_resetControl
177 */
178 /*@{*/
179 /**
180 * @def sa_STATE_RESET
181 * The Sub-System is in reset.
182 */
183 #define sa_STATE_RESET 0 /**< Sub-System state reset */
185 /**
186 * @def sa_STATE_ENABLE
187 * The Sub-System state is enabled.
188 */
189 #define sa_STATE_ENABLE 1 /**< Sub-System state enable */
191 /**
192 * @def sa_STATE_QUERY
193 * Query the Sub-System state.
194 */
195 #define sa_STATE_QUERY 2 /**< Query the Sub-System state */
197 /**
198 * @def sa_STATE_INCONSISTENT
199 * The Sub-System state is partially enabled.
200 */
201 #define sa_STATE_INCONSISTENT 3 /**< Sub-System is partially enabled */
203 /**
204 * @def sa_STATE_INVALID_REQUEST
205 * Invalid state command to the Sub-System.
206 */
207 #define sa_STATE_INVALID_REQUEST 4 /**< Invalid state command to the Sub-System */
209 /**
210 * @def sa_STATE_ENABLE_FAILED
211 * The Sub-System do not respond after restart.
212 */
213 #define sa_STATE_ENABLE_FAILED 5 /**< The Sub-System did not respond after restart */
214 /**
215 * @def sa_STATE_INVALID
216 * The Sub-System is at an invalid state for requested operation.
217 */
218 #define sa_STATE_INVALID 6 /**< The Sub-System at an invalid state for requested operation */
220 /*@}*/
221 /** @} */
223 /**
224 * @ingroup salld_api_structures
225 * @brief Sa_State_t defines the operating state of the security accelerator sub-system
226 *
227 * @details The values in @ref salldSubSysStates are used both to set the state of the security accelerator
228 * sub-system (sa_STATE_RESET and sa_STATE_ENABLE) as well as show the current state
229 * of the system (all values).
230 */
231 typedef int Sa_State_t;
233 /**
234 * @defgroup salldRetCodes SALLD Function Return Codes
235 * @ingroup salld_api_constants
236 * @{
237 *
238 * @name SALLD Function Return Codes
239 *
240 * Error codes returned by SALLD API functions.
241 */
242 /*@{*/
243 /**
244 * @def sa_ERR_OK
245 * SALLD Return Codes -- No Error.
246 */
247 #define sa_ERR_OK 0
248 /**
249 * @def sa_ERR_GEN
250 * SALLD Return Codes -- General Error.
251 */
252 #define sa_ERR_GEN -1
253 /**
254 * @def sa_ERR_PARAMS
255 * SALLD Return Codes -- Incorrect Input parameters.
256 */
257 #define sa_ERR_PARAMS -2
258 /**
259 * @def sa_ERR_NOMEM
260 * SALLD Return Codes -- Memory buffers not avialable.
261 */
262 #define sa_ERR_NOMEM -3
264 /**
265 * @def sa_ERR_INV_BUF
266 * SALLD Return Codes -- Invalid buffers.
267 */
268 #define sa_ERR_INV_BUF -4
269 /**
270 * @def sa_ERR_INV_PROTO_TYPE
271 * SALLD Return Codes -- Unsupported security protocol type.
272 */
273 #define sa_ERR_INV_PROTO_TYPE -5
274 /**
275 * @def sa_ERR_NO_CTX_BUF
276 * SALLD Return Codes -- Required Context Buffer not available.
277 */
278 #define sa_ERR_NO_CTX_BUF -6
279 /**
280 * @def sa_ERR_KEY_EXPIRED
281 * SALLD Return Codes -- Security Key is expired.
282 */
283 #define sa_ERR_KEY_EXPIRED -7
284 /**
285 * @def sa_ERR_REPLAY_OLD
286 * SALLD Return Codes -- Receive Packet is out of replay window range.
287 */
288 #define sa_ERR_REPLAY_OLD -8
289 /**
290 * @def sa_ERR_REPLAY_DUP
291 * SALLD Return Codes -- Duplicated Packet is received.
292 */
293 #define sa_ERR_REPLAY_DUP -9
294 /**
295 * @def sa_ERR_AUTH_FAIL
296 * SALLD Return Codes -- Authentication Failure.
297 */
298 #define sa_ERR_AUTH_FAIL -10
299 /**
300 * @def sa_ERR_PADDING_FAIL
301 * SALLD Return Codes -- ESP Padding Verification Failure.
302 */
303 #define sa_ERR_PADDING_FAIL -11
304 /**
305 * @def sa_ERR_CLOSE_PENDING
306 * SALLD Return Codes -- Close still pending, wait for Security context to be freed.
307 */
308 #define sa_ERR_CLOSE_PENDING -12
309 /**
310 * @def sa_ERR_UNSUPPORTED
311 * SALLD Return Codes -- API is not supported.
312 */
313 #define sa_ERR_UNSUPPORTED -13
314 /**
315 * @def sa_ERR_STATS_UNAVAIL
316 * SALLD Return Codes -- Statistics is not available yet.
317 */
318 #define sa_ERR_STATS_UNAVAIL -14
319 /**
320 * @def sa_ERR_MODULE_BUSY
321 * SALLD Return Codes -- Module (RNG or PKA) is busy serving pending request.
322 */
323 #define sa_ERR_MODULE_BUSY -15
324 /**
325 * @def sa_ERR_MODULE_UNAVAIL
326 * SALLD Return Codes -- Module (RNG or PKA) is not available (initialized) yet.
327 */
328 #define sa_ERR_MODULE_UNAVAIL -16
329 /**
330 * @def sa_ERR_PKA_TIMEOUT
331 * SALLD Return Codes -- PKA operation timeout..
332 */
333 #define sa_ERR_PKA_TIMEOUT -17
334 /**
335 * @def sa_ERR_SWINFO_UNAVAIL
336 * SALLD Return Codes -- Software Information is not available yet.
337 */
338 #define sa_ERR_SWINFO_UNAVAIL -18
339 /**
340 * @def sa_ERR_INV_HANDLE
341 * SALLD Return Codes -- Invalid system or channel handles.
342 */
343 #define sa_ERR_INV_HANDLE -19
344 /**
345 * @def sa_ERR_INV_ENDIAN_MODE
346 * SALLD Return Codes -- System or Channel instance using the different endian mode than the processor.
347 */
348 #define sa_ERR_INV_ENDIAN_MODE -20
349 /**
350 * @def sa_ERR_SCRATCH_MEMORY_FULL
351 * SALLD Return Codes -- No avail scratch memory for key storage
352 */
353 #define sa_ERR_SCRATCH_MEMORY_FULL -21
354 /**
355 * @def sa_ERR_PACKET
356 * SALLD Return Codes -- Error in the input packet such that SALLD is not able to process this packet.
357 */
358 #define sa_ERR_PACKET -22
360 /**
361 * @def sa_ERR_INV_INT_MEM
362 * SALLD Return Codes -- Invalid internal memory buffer for key storage
363 */
364 #define sa_ERR_INV_INT_MEM -23
366 /*@}*/
367 /** @} */
369 /**
370 * @defgroup SecurityProtocolTypes Security Protocol Types
371 * @ingroup salld_api_constants
372 * @{
373 *
374 * @name Security Protocol Types
375 *
376 * Definition of Security Protocol Types of the packets to
377 * be processed in the SALLD channel
378 *
379 */
380 /*@{*/
381 typedef enum {
382 sa_PT_NULL = 0, /**< No protocol: Data mode */
383 sa_PT_SRTP, /**< Security RTP */
384 sa_PT_SRTCP, /**< Security RTCP */
385 sa_PT_IPSEC_AH, /**< IPSEC AH mode */
386 sa_PT_IPSEC_ESP, /**< IPSEC ESP mode */
387 sa_PT_3GPP_AC /**< 3GPP Air Ciphering */
388 } Sa_SecProto_e;
389 /*@}*/
390 /** @} */
392 /**
393 * @defgroup CipherModes Cipher Modes
394 * @ingroup salld_api_constants
395 * @{
396 *
397 * @name Cipher Modes
398 *
399 * Definition of Cipher Modes used by the SA sub-engines
400 *
401 */
402 /*@{*/
403 typedef enum {
404 sa_CipherMode_NULL = 0, /**< No encryption */
405 sa_CipherMode_AES_CTR, /**< AES Counter mode */
406 sa_CipherMode_AES_F8, /**< AES F8 mode */
407 sa_CipherMode_AES_CBC, /**< AES CBC mode */
408 sa_CipherMode_DES_CBC, /**< DES CBC mode */
409 sa_CipherMode_3DES_CBC, /**< 3DES CBC mode */
410 sa_CipherMode_CCM, /**< Counter with CBC-MAC mode */
411 sa_CipherMode_GCM, /**< Galois Counter mode */
412 sa_CipherMode_GSM_A53, /**< 3GPP GSM A5/3 encryption: Key stream generation */
413 sa_CipherMode_ECSD_A53, /**< 3GPP ECSD A5/3 encryption: Key stream generation */
414 sa_CipherMode_GEA3, /**< 3GPP GPRA encryption: Key stream generation */
415 sa_CipherMode_KASUMI_F8, /**< 3GPP Kasumi F8 mode */
416 sa_CipherMode_SNOW3G_F8, /**< 3GPP Snow3G F8 mode */
417 sa_CipherMode_ZUC_F8, /**< 3GPP ZUC F8 mode (SASS_GEN2 only)*/
418 sa_CipherMode_LAST
419 } Sa_CipherMode_e;
420 /*@}*/
421 /** @} */
423 /**
424 * @defgroup AuthModes Authentication Modes
425 * @ingroup salld_api_constants
426 * @{
427 *
428 * @name Authentication Modes
429 * Definition of Authentication Modes used by the SA sub-engines
430 */
431 /*@{*/
432 typedef enum {
433 sa_AuthMode_NULL = 0, /**< No idviudal Authentication */
434 sa_AuthMode_MD5 = sa_CipherMode_LAST, /**< MD5 mode */
435 sa_AuthMode_SHA1, /**< SHA1 mode */
436 sa_AuthMode_SHA2_224, /**< 224-bit SHA2 mode */
437 sa_AuthMode_SHA2_256, /**< 256-bit SHA2 mode */
438 sa_AuthMode_HMAC_MD5, /**< HMAC with MD5 mode */
439 sa_AuthMode_HMAC_SHA1, /**< HMAC with SHA1 mode */
440 sa_AuthMode_HMAC_SHA2_224, /**< HMAC with 224-bit SHA2 mode */
441 sa_AuthMode_HMAC_SHA2_256, /**< HMAC with 256-bit SHA2 mode */
442 sa_AuthMode_GMAC, /**< Galois Message Authentication Code mode */
443 sa_AuthMode_GMAC_AH, /**< Galois Message Authentication Code mode for IPSEC AH operation
444 @note: This mode is used at Data Mode only */
445 sa_AuthMode_CMAC, /**< Cipher-based Message Authentication Code mode */
446 sa_AuthMode_CBC_MAC, /**< Cipher Block Chaining - Message Authentication Code mode */
447 sa_AuthMode_AES_XCBC, /**< AES Extended Cipher Block Chaining - Message Authentication Code mode */
448 sa_AuthMode_KASUMI_F9, /**< 3GPP Kasumi F9 mode */
449 sa_AuthMode_SNOW3G_F9, /**< 3GPP Snow3G F9 mode (SASS_GEN2 only) */
450 sa_AuthMode_ZUC_F9 /**< 3GPP ZUC F9 mode (SASS_GEN2 only) */
451 } Sa_AuthMode_e;
452 /*@}*/
453 /** @} */
455 /**
456 * @ingroup salld_api_structures
457 * @brief Specification of Sa_ChanHandle
458 * The Sa_ChanHandle is used to identify a SALLD channel instance
459 */
460 typedef void* Sa_ChanHandle;
462 /**
463 * @defgroup saSizeConfigCtrlBit SA Size Configuration Control Bit Definitions
464 * @ingroup salld_api_constants
465 * @{
466 *
467 * @name SA Size Configuration Control Bit Definitions
468 *
469 * Bitmap definition of the ctrlBitMap in Sa_ChanSizeCfg_t and Sa_SizeCfg_t.
470 *
471 */
472 /*@{*/
473 /**
474 * @def sa_SIZE_CONFIG_CREATE_SHADOW_INST
475 * Control Info -- 0:Do not create shadow instance (refer to @ref appendix2)
476 * 1:Create Shadow instance for mixed-endianness operation
477 */
479 #define sa_SIZE_CONFIG_CREATE_SHADOW_INST 0x0001
482 /**
483 * @def sa_SIZE_CONFIG_SASS_GEN2
484 * Control Info -- 0:First generation Security Accelerator Sub-System (SASS)
485 * 1:Second generattion SASS at more advanced keystone2 devices such as Lamarr and Edison
486 * (TBD: to be replaced with part number)
487 */
489 #define sa_SIZE_CONFIG_SASS_GEN2 0x0002
491 /*@}*/
492 /** @} */
494 /**
495 * @ingroup salld_api_structures
496 * @brief SALLD channel size configuration structure
497 *
498 * DESCRIPTION: Data structure that defines memory requirements for SALLD channel instance
499 *
500 */
501 typedef struct {
502 Sa_SecProto_e protocolType; /**< Security protocol type as defined by @ref SecurityProtocolTypes */
503 int cacheLineSize; /**< Specify the size of cache line of the memory where the channel buffers will reside.
504 Set this variable to 0 if this channel is not shared among multiple cores
505 @note cacheLineSize should be the larger of cache line sizes amoung mixed processors */
506 uint16_t ctrlBitMap; /**< Various configuration information as specified at @ref saSizeConfigCtrlBit */
507 } Sa_ChanSizeCfg_t;
509 /**
510 * @ingroup salld_api_structures
511 * @brief SALLD Channel Configuration structure
512 *
513 * Data structure providing configuration information in Sa_chanInit()
514 *
515 */
516 typedef struct {
517 uint32_t ID; /**< User specified channel ID */
518 Sa_ChanSizeCfg_t sizeConfig; /**< SALLD memory allocation requirement structure */
519 uint16_t engSelect; /**< User selected encryption/authentication engine set number,
520 valid only when Sa_Config_t.engSelMode is sa_EngSelMode_USERSPECIFIED */
521 } Sa_ChanConfig_t;
523 /**
524 * @ingroup salld_api_structures
525 * @brief SRTP Configuration Parameters structure
526 *
527 * Data structure defines the SRTP specific configuration parameters excluding the keys
528 *
529 */
530 typedef struct {
531 uint16_t masterKeySize; /**< Specify the size of the master key in bytes */
532 uint16_t masterSaltSize; /**< Specify the size of the master salt in bytes */
533 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key in bytes */
534 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
535 uint16_t sessionSaltSize; /**< Specify the size of the session salt in bytes */
536 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
537 } Sa_SrtpConfigParams_t;
539 /**
540 * @defgroup saIpsecTransportTypes IPSEC Transport Types
541 * @ingroup salld_api_constants
542 * @{
543 *
544 * @name IPSEC Transport Types
545 *
546 * Parameter transportType of Sa_IpsecConfigParams_t should be set to
547 * one of these transport types.
548 */
549 /*@{*/
550 typedef enum {
551 sa_IPSEC_TRANSPORT_TRANSPORT = 0, /**< Trasport mode */
552 sa_IPSEC_TRANSPORT_TUNNEL /**< Tunnel mode */
553 } Sa_IpsecTransportType_e;
554 /*@}*/
555 /** @} */
557 /**
558 * @defgroup saIpsecConfigCtrlBit IPSEC Configuration Control Bit Definitions
559 * @ingroup salld_api_constants
560 * @{
561 *
562 * @name IPSEC Configuration Control Bit Definitions
563 *
564 * Bitmap definition of the ctrlBitMap in salldInpsecConfigParams_t.
565 *
566 */
567 /*@{*/
568 /**
569 * @def sa_IPSEC_CONFIG_ESN
570 * Control Info -- 0:Disable Extended Sequence Number
571 * 1:Enable Extended Sequence Number
572 */
573 #define sa_IPSEC_CONFIG_ESN 0x0001
574 /**
575 * @def sa_IPSEC_CONFIG_PERMANENT_SC
576 * Control Info -- 0:The corresponding security context is marked as second tier
577 * 1:The corresponding security context ia marked as first tier so that it will
578 * not be evicted automatically.
579 */
580 #define sa_IPSEC_CONFIG_PERMANENT_SC 0x0002
581 /*@}*/
582 /** @} */
584 /**
585 * @ingroup salld_api_structures
586 * @brief IPSEC Configuration Parameters structure
587 *
588 * Data structure defines the IPSEC specific configuration parameters excluding the keys
589 *
590 */
591 typedef struct {
592 uint16_t transportType; /**< Specify the transport Type as defined at @ref saIpsecTransportTypes */
593 uint16_t ctrlBitMap; /**< Various control information as specified at @ref saIpsecConfigCtrlBit */
594 uint16_t encryptionBlockSize; /**< Specify the encryption block size
595 1: Stream encryption and no alignment requirement
596 4: AES-CTR or other stream-like encryption with 4-byte
597 alignment
598 block size: block encryption algorithm */
599 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key in bytes */
600 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
601 uint16_t sessionSaltSize; /**< Specify the size of the session salt in bytes */
602 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
603 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
604 uint16_t nextHdr; /**< Specify the next protocol header */
605 /**< @note: This parameter is no longer used. */
606 uint32_t spi; /**< Specify the SPI (Security Parameter Index) */
607 uint32_t esnLo; /**< Specify the initial value of the (extended) sequence Number (lower 32-bit) */
608 uint32_t esnHi; /**< Specify the initial value of the extended sequence Number (upper 32-bit) */
609 } Sa_IpsecConfigParams_t;
611 /**
612 * @defgroup AcPduTypes Air Ciphering PDU Types
613 * @ingroup salld_api_constants
614 * @{
615 *
616 * @name Air Ciphering PDU Types
617 *
618 * Definition of Air Ciphering PDU Types supported in SA
619 * Parameter pduType of Sa_AcConfigParams_t should be set to
620 * one of these types. Refer to @ref appendix1 for detailed
621 * description
622 *
623 */
624 /*@{*/
625 typedef enum {
626 sa_AcPduType_GSM = 0, /**< All GSM PDUs */
627 sa_AcPduType_WCDMA_TMD, /**< WCDMA MAC TMD */
628 sa_AcPduType_WCDMA_UMD, /**< WCDMA RLC UMD */
629 sa_AcPduType_WCDMA_AMD, /**< WCDMA RLC AMD */
630 sa_AcPduType_LTE, /**< LTE PDCP PDUs */
631 sa_AcPduType_LTE_CP /**< PDCP Control Plane Data Uint for SRBs */
632 } Sa_AcPduType_e;
633 /*@}*/
634 /** @} */
636 /**
637 * @defgroup SALLDAcConfigCtrlBit AC Configuration Control Bit Definitions
638 * @ingroup salld_api_constants
639 * @{
640 *
641 * @name AC Configuration Control Bit Definitions
642 *
643 * Bitmap definition of the ctrlBitMap in Sa_AcConfigParams_t.
644 *
645 */
646 /*@{*/
647 /**
648 * @def sa_AC_CONFIG_BEARER_MASK
649 * Control Info -- 5-bit or 8-bit Bearer mask
650 */
651 #define sa_AC_CONFIG_BEARER_MASK 0x00FF
652 /**
653 * @def sa_AC_CONFIG_DIR
654 * Control Info -- 0:UE to RNC(uplink)
655 * 1:RNC to UE(downlink)
656 */
657 #define sa_AC_CONFIG_DIR 0x0100
658 /**
659 * @def sa_AC_CONFIG_COPY_COUNTC
660 * Control Info -- 1: Copy Count-C into the timestamp field within CPPI Descriptor for reference
661 * 0: Otherwise
662 */
663 #define sa_AC_CONFIG_COPY_COUNTC 0x0200
665 /**
666 * @def sa_AC_CONFIG_COUNTC_BY_APP
667 * Control Info -- 1: Count-C is provided by application.
668 * 0: Count-C is incremented and stored at SASS
669 *
670 * @note: This flag is only applicable for the to-air traffic when PDU type is set to LTE
671 * where the count-C is maintained by SASS by default.
672 * This flag may be used to inform SASS that the count-C will be provided by application
673 * for LTE data traffic in slow path.
674 */
675 #define sa_AC_CONFIG_COUNTC_BY_APP 0x0400
677 /**
678 * @def sa_AC_CONFIG_KEY_IN_SCRATCH
679 * Control Info -- 0:key is copied into security context by lld
680 * 1:key is copied into scratch memory by lld
681 */
682 #define sa_AC_CONFIG_KEY_IN_SCRATCH 0x0800
684 /*@}*/
685 /** @} */
687 /**
688 * @ingroup salld_api_structures
689 * @brief AC (Air Ciphering) Configuration Parameters structure
690 *
691 * Data structure defines the AC specific configuration parameters excluding the keys
692 *
693 */
695 typedef struct {
696 uint32_t countC; /**< Specify the high bits, HFN, for the frame Counter
697 WCDMA RLC AM: the high 20 bits are used
698 WCDMA RLC UM: the high 25 bits are used
699 WCDMA RLC TM: the high 25 bits are used
700 LTE: All 32-bit is used as Count-C
701 GSM: Not used */
702 uint32_t fresh; /**< Specify the 32-bit random number (fresh) required
703 for some integrity check algorithms */
704 uint32_t ivLow26; /**< Specify the low 26-bit value of the initialization vector */
705 uint16_t pduType; /**< Specify the Air Ciphering PDU Type as defined at @ref Sa_AcPduType_e */
706 uint16_t ctrlBitMap; /**< Various control information as specified at @ref SALLDAcConfigCtrlBit */
707 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key (Kc) in bytes
708 Note: The LLD may expand the key stream based on the encryption mode */
709 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
710 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
711 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
712 } Sa_AcConfigParams_t;
714 /**
715 * @ingroup salld_api_structures
716 * @brief Data Mode Configuration Parameters structure
717 *
718 * Data structure defines the Data Mode specific configuration parameters excluding the keys.
719 *
720 * Due to hardware limiations in IP, below restrictions apply :
721 *
722 @verbatim
723 ---------------------------------------------------------------------------
724 | Cipher Mode | Restriction |
725 ---------------------------------------------------------------------------
726 | - sa_CipherMode_CCM | - (IV Size + Salt Size) should not exceed 13 |
727 | | - AAD size should not exceed 14 |
728 | | - authentication mode should not be null |
729 ---------------------------------------------------------------------------
730 | - sa_CipherMode_GCM | - (IV Size + Salt Size) should be 12 |
731 | | - AAD size should not exceed 16 |
732 | | - authentication mode should not be null |
733 ---------------------------------------------------------------------------
734 | - sa_CipherMode_DES_CBC | - (IV Size should be 8 |
735 | | - Salt size should be 0 |
736 ---------------------------------------------------------------------------
737 | - sa_CipherMode_3DES_CBC | - (IV Size should be 8 |
738 | | - Salt size should be 0 |
739 ---------------------------------------------------------------------------
740 | - sa_CipherMode_KASUMI_F8| - (IV Size should be 8 |
741 | | |
742 ---------------------------------------------------------------------------
743 | - sa_CipherMode_SNOW3G_F8| - (IV Size should be 16 |
744 | | |
745 ---------------------------------------------------------------------------
747 ---------------------------------------------------------------------------
748 | Auth Mode | Restriction |
749 ---------------------------------------------------------------------------
750 | - sa_AuthMode_GMAC | - (IV Size + Salt Size) should be 12 |
751 | | - AAD size should not exceed 16 |
752 | | - cipher mode should not be null |
753 ---------------------------------------------------------------------------
754 | - sa_AuthMode_GMAC_AH | - (IV Size should be 8 |
755 | | - Salt size should be 4 |
756 | | - cipher mode should not be null |
757 ---------------------------------------------------------------------------
758 | - sa_AuthMode_KASUMI_F9 | - (IV Size should be 8 |
759 | | |
760 ---------------------------------------------------------------------------
761 @endverbatim
762 */
763 typedef struct {
764 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key in bytes */
765 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
766 uint16_t sessionSaltSize; /**< Specify the size of the session salt used in the GCM/CCM operation in bytes */
767 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
768 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
769 uint16_t aadSize; /**< Specify the size of the additional authenticated data in bytes used in CCM and GCM modes */
770 uint16_t enc; /**< TRUE: Encryption(To-Air); FALSE: Decryption (From-Air)*/
771 uint16_t enc1st; /**< TRUE: Perform encryption first; FALSE: Perform authentication first */
772 } Sa_DataModeConfigParams_t;
774 /**
775 * @ingroup salld_api_structures
776 * @brief SALLD Protocol-specfic Configuration Parameters structure
777 *
778 * Data structure defines the security protocol specific configuration parameters
779 *
780 */
781 typedef union {
782 Sa_SrtpConfigParams_t srtp; /**< Specify the configuration parameters for SRTP */
783 Sa_IpsecConfigParams_t ipsec; /**< Specify the configuration parameters for IPSEC */
784 Sa_AcConfigParams_t ac; /**< Specify the configuration parameters for Air Ciphering */
785 Sa_DataModeConfigParams_t data; /**< Specify the configuration parameters for Data Mode */
786 } Sa_ProtocolConfigParams_t;
788 /**
789 * @defgroup SALLDDestInfoCtrlBit SALLD Destination Info Control Bit Definitions
790 * @ingroup salld_api_constants
791 * @{
792 *
793 * @name SALLD Destination Info Control Bit Definitions
794 * Bitmap definition of the ctrlBitfield in Sa_DestInfo_t
795 * It allows selective enabling/disabling of specific SALLD operations
796 *
797 */
798 /*@{*/
799 /**
800 * @def sa_DEST_INFO_CTRL_USE_LOC_DMA
801 * Control Info -- Set: Use Local DMA
802 * Clear: Use Global DMA (defAult)
803 *
804 * There are Network Sub-System (NSS) internal DMA resources including CPPI and QMSS which can be used to transfer packets within
805 * the NSS such as from PASS to SASS and vica versa. This control bit is used to enable local DMA tranfer from SASS to PASS.
806 *
807 * @note: This feature is only supported at the second generation NSS devices.
808 */
809 #define sa_DEST_INFO_CTRL_USE_LOC_DMA 0x01
810 /*@}*/
811 /** @} */
814 /**
815 * @ingroup salld_api_structures
816 * @brief SALLD Destination Info structure
817 *
818 * Data structure defines the destination parameters which are used
819 * by SASS to deliver the processed packets to the desired destination
820 *
821 */
822 typedef struct {
823 uint8_t ctrlBitfield; /**< Control Bit Map to specify destination related operations such as local DMA
824 as defined at @ref SALLDDestInfoCtrlBit */
826 uint8_t flowID; /**< Specify the 8-bit CPPI Flow ID */
827 uint16_t queueID; /**< Specify the 16-bit destination Queue ID */
828 uint32_t swInfo0; /**< User-defined channel-specific parameter which will be placed in SwInfo0 for packets from SA */
829 uint32_t swInfo1; /**< User-defined channel-specific parameter which will be placed in SwInfo1 for packets from SA */
830 } Sa_DestInfo_t;
832 /**
833 * @ingroup salld_api_structures
834 * @brief SALLD General Configuration Parameters structure
835 *
836 * Data structure defines the general configuration parameters excluding the keys and related
837 * re-key parameters
838 *
839 */
840 typedef struct {
841 Sa_CipherMode_e cipherMode; /**< Specify the cipher mode as defined at @ref CipherModes */
842 Sa_AuthMode_e authMode; /**< Specify the authentication mode as defined at @ref AuthModes */
843 Sa_DestInfo_t destInfo; /**< Specify the post-SA destination information */
844 Sa_ProtocolConfigParams_t params; /**< Specify the protocol-specific configuration parameters */
845 } Sa_GenConfigParams_t;
847 /**
848 * @defgroup SALLDCtrlInfoValidBit SALLD General Control Info Valid Bit Definitions
849 * @ingroup salld_api_constants
850 * @{
851 *
852 * @name SALLD General Control Info Valid Bit Definitions
853 * Bitmap definition of the validBitfield in Sa_GenCtrlInfo_t.
854 * It allows selective control parameters
855 */
856 /*@{*/
857 /**
858 * @def sa_CONTROLINFO_VALID_CTRL_BITMAP
859 * Control Info -- ctrlBitfield
860 */
861 #define sa_CONTROLINFO_VALID_CTRL_BITMAP 0x0001
862 /**
863 * @def sa_CONTROLINFO_VALID_TX_CTRL
864 * Control Info -- txCtrl
865 */
866 #define sa_CONTROLINFO_VALID_TX_CTRL 0x0002
867 /**
868 * @def sa_CONTROLINFO_VALID_RX_CTRL
869 * Control Info -- rtxCtrl
870 */
871 #define sa_CONTROLINFO_VALID_RX_CTRL 0x0004
872 /**
873 * @def sa_CONTROLINFO_VALID_REPLAY_WIN
874 * Control Info -- replayWindowSize
875 */
876 #define sa_CONTROLINFO_VALID_REPLAY_WIN 0x0008
877 /*@}*/
878 /** @} */
880 /**
881 * @defgroup SALLDCtrlInfoCtrlBit SALLD General Control Info Control Bit Definitions
882 * @ingroup salld_api_constants
883 * @{
884 *
885 * @name SALLD General Control Info Control Bit Definitions
886 * Bitmap definition of the ctrlBitfield in Sa_GenCtrlInfo_t.
887 * It allows selective enabling/disabling of specific SALLD operations
888 *
889 */
890 /*@{*/
891 /**
892 * @def sa_CONTROLINFO_CTRL_TX_ON
893 * Control Info -- Enable Tx
894 */
895 #define sa_CONTROLINFO_CTRL_TX_ON 0x0001
896 /**
897 * @def sa_CONTROLINFO_CTRL_RX_ON
898 * Control Info -- Enable Rx
899 */
900 #define sa_CONTROLINFO_CTRL_RX_ON 0x0002
901 /**
902 * @def sa_CONTROLINFO_CTRL_TX_RX_MASK
903 * Control Info -- Tx/Rx Control
904 * Bit Mask
905 */
906 #define sa_CONTROLINFO_CTRL_TX_RX_MASK 0x0003
907 /**
908 * @def sa_CONTROLINFO_CTRL_SW_ONLY
909 * Control Info -- Software support only.
910 * It is used for the protocols which are not supported by the SA
911 * firmware such as SRTCP.
912 */
913 #define sa_CONTROLINFO_CTRL_SW_ONLY 0x0008
914 /**
915 * @def sa_CONTROLINFO_CTRL_OP_MASK
916 * Control Info -- Operation Control
917 * Bit Mask
918 */
919 #define sa_CONTROLINFO_CTRL_OP_MASK 0x000b
920 /*@}*/
921 /** @} */
923 /**
924 * @ingroup salld_api_structures
925 * @brief SALLD General Control Information structure
926 *
927 * Data structure defines the general control information of the security channel excluding the keys
928 * and related re-key parameters
929 *
930 */
931 typedef struct {
932 uint16_t validBitfield; /**< Specify valid parameters as defined at @ref SALLDCtrlInfoValidBit */
933 uint16_t ctrlBitfield; /**< Control Bit Map to specify tx/rx and other operations
934 as defined at @ref SALLDCtrlInfoCtrlBit */
935 Sa_GenConfigParams_t txCtrl; /**< Specify the general configuration parameters in Tx
936 (to-network) direction */
937 Sa_GenConfigParams_t rxCtrl; /**< Specify the general configuration parameters in Rx
938 (from-network) direction */
939 uint16_t replayWindowSize; /**< Specify the size of the replay window
940 (SRTP 64 IPSEC 64:128) */
941 } Sa_GenCtrlInfo_t;
943 /**
944 * @defgroup SALLDSrtpKeyCtrlInfo SALLD SRTP Key Control Info Bit Definitions
945 * @ingroup salld_api_constants
946 * @{
947 *
948 * @name SRTP Key Control Info Bit Definitions
949 *
950 * Bitmap definition of the ctrlBitfield in Sa_SrtpKeyParams_t.
951 */
952 /*@{*/
953 /**
954 * @def sa_SRTP_KEY_CTRL_MASTER_KEY
955 * Control Info -- Set: MASTER_KEY available
956 */
957 #define sa_SRTP_KEY_CTRL_MASTER_KEY 0x0001
958 /**
959 * @def sa_SRTP_KEY_CTRL_MASTER_SALT
960 * Control Info -- Set: MASTER_SALT available
961 */
962 #define sa_SRTP_KEY_CTRL_MASTER_SALT 0x0002
963 /**
964 * @def sa_SRTP_KEY_CTRL_KEY_DERIVE_RATE
965 * Control Info -- Set: key derivation rate available
966 */
967 #define sa_SRTP_KEY_CTRL_KEY_DERIVE_RATE 0x0004
968 /**
969 * @def sa_SRTP_KEY_CTRL_KEY_LIFETIME
970 * Control Info -- Set: key lifetime available
971 */
972 #define sa_SRTP_KEY_CTRL_KEY_LIFETIME 0x0008
973 /**
974 * @def sa_SRTP_KEY_CTRL_ROC
975 * Control Info -- Set: Initial ROC is available
976 */
977 #define sa_SRTP_KEY_CTRL_ROC 0x0010
979 /**
980 * @def sa_SRTP_KEY_CTRL_MKI
981 * Control Info -- Set: MKI available
982 */
983 #define sa_SRTP_KEY_CTRL_MKI 0x0020
984 /**
985 * @def sa_SRTP_KEY_CTRL_KEY_TYPE_FROM_TO
986 * Control Info -- Set: From To Key
987 * Clear: MKI Key
988 */
989 #define sa_SRTP_KEY_CTRL_KEY_TYPE_FROM_TO 0x0040
990 /*@}*/
991 /** @} */
993 /**
994 * @ingroup salld_api_structures
995 * @brief SRTP Key Information structure
996 *
997 * Data structure defines the SRTP Key related parameters
998 *
999 */
1000 typedef struct {
1001 uint16_t ctrlBitfield; /**< Specify the Key types and other control information as defined at @ref SALLDSrtpKeyCtrlInfo */
1002 uint8_t* masterKey; /**< Specify the master key */
1003 uint8_t* masterSalt; /**< Specify the master Salt */
1004 uint16_t derivRate; /**< Specify the key derivation rate in n of 2^n format (where 0 <= n <= 24)
1005 if not set then use default value, i.e no key derivation */
1006 uint16_t keyLifeTimeMsw; /**< Specify the maximum number of packets allowed for the master
1007 key combination */
1008 uint32_t keyLifeTimeLsw; /**< Specify the maximum number of packets allowed for the master
1009 key combination */
1010 uint32_t roc; /**< SRTP: Specify the initial value of the rollover counter
1011 SRTCP: Specify the initial index at the tx packet */
1012 uint32_t fromEsnMsw; /**< Specify the starting 48-bit extended sequence number
1013 of the specified From-To keys */
1014 uint16_t fromEsnLsw; /**< Specify the starting 48-bit extended sequence number
1015 of the specified From-To keys */
1016 uint32_t toEsnMsw; /**< Specify the last 48-bit extended sequence number
1017 of the specified From-To keys */
1018 uint16_t toEsnLsw; /**< Specify the last 48-bit extended sequence number
1019 of the specified From-To keys */
1020 uint16_t mkiSize; /**< Specify the size of the MKI in bytes */
1021 uint32_t mki; /**< Specify the MKI value */
1022 } Sa_SrtpKeyParams_t;
1024 /**
1025 * @ingroup salld_api_constants
1026 * @brief Define the maximum key size supported by SASS
1027 */
1028 #define SALLD_MAX_KEY_SIZE 32
1030 /**
1031 * @defgroup SALLDIpsecKeyCtrlInfo SALLD IPSEC Key Control Info Bit Definitions
1032 * @ingroup salld_api_constants
1033 * @{
1034 *
1035 * @name IPSEC Key Control Info Bit Definitions
1036 *
1037 * Bitmap definition of the ctrlBitfield in Sa_IpsecKeyParams_t.
1038 */
1039 /*@{*/
1040 /**
1041 * @def sa_IPSEC_KEY_CTRL_ENC_KEY
1042 * Control Info -- Set: ENC_KEY available
1043 */
1044 #define sa_IPSEC_KEY_CTRL_ENC_KEY 0x0001
1045 /**
1046 * @def sa_IPSEC_KEY_CTRL_MAC_KEY
1047 * Control Info -- Set: MAC_KEY available
1048 */
1049 #define sa_IPSEC_KEY_CTRL_MAC_KEY 0x0002
1050 /**
1051 * @def sa_IPSEC_KEY_CTRL_SALT
1052 * Control Info -- Set: Session Salt available
1053 */
1054 #define sa_IPSEC_KEY_CTRL_SALT 0x0004
1055 /*@}*/
1056 /** @} */
1058 /**
1059 * @ingroup salld_api_structures
1060 * @brief IPSEC Key Information structure
1061 *
1062 * Data structure defines the IPSEC Key related parameters
1063 *
1064 */
1065 typedef struct {
1066 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information as defined at @ref SALLDIpsecKeyCtrlInfo */
1067 uint8_t* sessionEncKey; /**< Specify the session encryption key */
1068 uint8_t* sessionAuthKey; /**< Specify the session authentication key */
1069 uint8_t* sessionSalt; /**< Specify the session salt */
1070 } Sa_IpsecKeyParams_t;
1072 /**
1073 * @defgroup SALLDAcKeyCtrlInfo SALLD AC Key Control Info Bit Definitions
1074 * @ingroup salld_api_constants
1075 * @{
1076 *
1077 * @name Air Ciphering Key Control Info Bit Definitions
1078 *
1079 * Bitmap definition of the ctrlBitfield in Sa_AcKeyParams_t.
1080 */
1081 /*@{*/
1082 /**
1083 * @def sa_AC_KEY_CTRL_ENC_KEY
1084 * Control Info -- Set: ENC_KEY available
1085 */
1086 #define sa_AC_KEY_CTRL_ENC_KEY 0x0001
1087 /**
1088 * @def sa_AC_KEY_CTRL_MAC_KEY
1089 * Control Info -- Set: MAC_KEY available
1090 */
1091 #define sa_AC_KEY_CTRL_MAC_KEY 0x0002
1092 /*@}*/
1093 /** @} */
1095 /**
1096 * @ingroup salld_api_structures
1097 * @brief Air Ciphering Key Information structure
1098 *
1099 * Data structure defines the Air Ciphering Key related parameters
1100 *
1101 */
1102 typedef struct {
1103 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information as defined at @ref SALLDAcKeyCtrlInfo */
1104 uint8_t* sessionEncKey; /**< Specify the session encryption key */
1105 uint8_t* sessionAuthKey; /**< Specify the session authentication key */
1106 } Sa_AcKeyParams_t;
1108 /**
1109 * @defgroup SALLDDataModeKeyCtrlInfo SALLD Data Mode Key Control Info Bit Definitions
1110 * @ingroup salld_api_constants
1111 * @{
1112 *
1113 * @name Data Mode Key Control Info Bit Definitions
1114 *
1115 * Bitmap definition of the ctrlBitfield in Sa_DataModeKeyParams_t.
1116 */
1117 /*@{*/
1118 /**
1119 * @def sa_DATA_MODE_KEY_CTRL_ENC_KEY
1120 * Control Info -- Set: ENC_KEY available
1121 */
1122 #define sa_DATA_MODE_KEY_CTRL_ENC_KEY 0x0001
1123 /**
1124 * @def sa_DATA_MODE_KEY_CTRL_MAC_KEY
1125 * Control Info -- Set: MAC_KEY available
1126 */
1127 #define sa_DATA_MODE_KEY_CTRL_MAC_KEY 0x0002
1128 /**
1129 * @def sa_DATA_MODE_KEY_CTRL_SALT
1130 * Control Info -- Set: SALT available
1131 */
1132 #define sa_DATA_MODE_KEY_CTRL_SALT 0x0004
1133 /*@}*/
1134 /** @} */
1136 /**
1137 * @ingroup salld_api_structures
1138 * @brief Data Mode Key Information structure
1139 *
1140 * Data structure defines the Data Mode Key related parameters
1141 *
1142 */
1143 typedef struct {
1144 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information as defined at @ref SALLDDataModeKeyCtrlInfo */
1145 uint8_t* sessionEncKey; /**< Specify the session encryption key */
1146 uint8_t* sessionAuthKey; /**< Specify the session authentication key */
1147 uint8_t* sessionSalt; /**< Specify the session salt in GCM/CCM only */
1148 } Sa_DataModeKeyParams_t;
1150 /**
1151 * @ingroup salld_api_structures
1152 * @brief Protocol-Specific Key Information structure
1153 *
1154 * Data structure defines the protocol-specific Key related parameters
1155 *
1156 */
1157 typedef union {
1158 Sa_SrtpKeyParams_t srtp; /**< Specify the key related parameters for SRTP/SRTCP */
1159 Sa_IpsecKeyParams_t ipsec; /**< Specify the key related parameters for IPSEC */
1160 Sa_AcKeyParams_t ac; /**< Specify the key related parameters for 3GPP Air Ciphering */
1161 Sa_DataModeKeyParams_t data; /**< Specify the key related parameters in Data Mode */
1162 } Sa_ProtocolKeyParams_t;
1164 /**
1165 * @defgroup SALLDKeyCtrlInfo SALLD Key Control Info Control Bit Definitions
1166 * @ingroup salld_api_constants
1167 * @{
1168 *
1169 * @name SALLD Key Control Info Control Bit Definitions
1170 *
1171 * Bitmap definition of the ctrlBitfield in Sa_KeyCtrlInfo_t.
1172 */
1173 /*@{*/
1174 /**
1175 * @def sa_KEY_CONTROL_TX_KEY_VALID
1176 * Control Info -- TX key is valid
1177 */
1178 #define sa_KEY_CONTROL_TX_KEY_VALID 0x0001
1179 /**
1180 * @def sa_KEY_CONTROL_RX_KEY_VALID
1181 * Control Info -- RX key is valid
1182 */
1183 #define sa_KEY_CONTROL_RX_KEY_VALID 0x0002
1184 /* @} */ /* ingroup */
1185 /** @} */
1187 /**
1188 * @ingroup salld_api_structures
1189 * @brief SALLD Key Control Information structure
1190 *
1191 * Data structure defines the Key related information of the security channel.
1192 * It is used for initial channel configuration and re-key operation.
1193 *
1194 */
1195 typedef struct {
1196 uint16_t ctrlBitfield; /**< Bit Map to specify tx/rx and other operations as
1197 defined at @ref SALLDKeyCtrlInfo */
1198 Sa_ProtocolKeyParams_t txKey; /**< Specify the security key parameters in Tx
1199 (to-network) direction */
1200 Sa_ProtocolKeyParams_t rxKey; /**< Specify the security key parameters in Rx
1201 (from-network) direction */
1202 } Sa_KeyCtrlInfo_t;
1204 /**
1205 * @defgroup salldChanCtrlType SALLD Channel Control Type
1206 * @ingroup salld_api_constants
1207 * @{
1208 *
1209 * @name Channel Control Type
1210 * Definition of channel control types supported by SA LLD
1211 * Parameter ctrlType of Sa_ChanCtrlInfo_t should be set to
1212 * one of these types.
1213 *
1214 */
1215 /*@{*/
1216 typedef enum {
1217 sa_CHAN_CTRL_GEN_CONFIG = 1, /**< Security Channel General Configuration */
1218 sa_CHAN_CTRL_KEY_CONFIG = 2 /**< Security Channel Key Configuration */
1219 } Sa_ChanControlCode_e;
1220 /*@}*/
1221 /** @} */
1223 /**
1224 * @ingroup salld_api_structures
1225 * @brief Channel Control Information structure
1226 *
1227 * Data structure providing control information in Sa_chanControl()
1228 *
1229 */
1230 typedef struct {
1231 uint16_t ctrlType; /**< Specify the channel control type as defined at @ref Sa_ChanControlCode_e */
1232 union {
1233 Sa_GenCtrlInfo_t gen; /**< Specify the general control information */
1234 Sa_KeyCtrlInfo_t key; /**< Specify the key control information */
1235 }ctrlInfo; /**< Contain the control-type specific control information */
1237 } Sa_ChanCtrlInfo_t;
1239 /**
1240 * @defgroup PktErrorCodes SALLD PKT Error Codes
1241 * @ingroup salld_api_constants
1242 * @{
1243 *
1244 * @name SALLD PKT Error Codes
1245 *
1246 * Definitions of the error codes for the packets received from SA
1247 */
1248 /*@{*/
1249 /**
1250 * @def sa_PKT_ERR_OK
1251 * SALLD Packet Error code -- No Error.
1252 */
1253 #define sa_PKT_ERR_OK 0
1254 /**
1255 * @def sa_PKT_ERR_REPLAY_OLD
1256 * SALLD Packet Error code -- Packet rejected by SA because it is out of replay window range.
1257 */
1258 #define sa_PKT_ERR_REPLAY_OLD 1
1259 /**
1260 * @def sa_PKT_ERR_REPLAY_DUP
1261 * SALLD Packet Error code -- Packet rejected by SA because it is duplicated.
1262 */
1263 #define sa_PKT_ERR_REPLAY_DUP 2
1264 /**
1265 * @def sa_PKT_ERR_INVALID_KEY
1266 * SALLD Packet Error code -- Packet rejected by SA because the key in the security
1267 * context is out of date.
1268 */
1269 #define sa_PKT_ERR_INVALID_KEY 3
1270 /**
1271 * @def sa_PKT_ERR_INVALID_MKI
1272 * SALLD Packet Error code -- Packet rejected by SA because the MKI in the security
1273 * context does not match the one in the packet.
1274 */
1275 #define sa_PKT_ERR_INVALID_MKI 4
1276 /**
1277 * @def sa_PKT_ERR_AUTH_FAIL
1278 * SALLD Packet Error code -- Packet rejected by SA because authentication failed.
1279 */
1280 #define sa_PKT_ERR_AUTH_FAIL 5
1281 /*@}*/
1282 /** @} */
1284 /**
1285 * @ingroup salld_api_structures
1286 * @brief SA Packet Error data type
1287 *
1288 * Data type defines the packet error type of all packets to be delivered to SA.
1289 *
1290 */
1291 typedef uint16_t Sa_PktErr_t;
1293 /**
1294 * @defgroup SaPktDir SA Packet Directions
1295 * @ingroup salld_api_constants
1296 * @{
1297 *
1298 * @name SA Packet Directions
1299 *
1300 * Definition of SA Packet Directions used at API @ref Sa_chanGetSwInfo
1301 */
1302 /*@{*/
1303 typedef enum {
1304 sa_PKT_DIR_FROM_NETWORK = 0, /**< Form-network (To-air) packet */
1305 sa_PKT_DIR_TO_NETWORK /**< To-network (From-air) packet */
1306 } Sa_PktDir_t;
1307 /*@}*/
1308 /** @} */
1310 /**
1311 * @ingroup salld_api_constants
1312 * @brief Define the maxmium number of software info parameters at @ref Sa_SWInfo_t.
1313 */
1314 #define sa_MAX_SW_INFO_SIZE 3
1316 /**
1317 * @ingroup salld_api_structures
1318 * @brief SA Software Information structure
1319 *
1320 * Data structure defines the SA-specific software information required for all packets to
1321 * be delivered to SA. It will be provided by the SA LLD based on the channel configuration
1322 * parameters and the security protocols.The software information words should be copied
1323 * to the CPPI Software words area as provided through the CPPI LLD or equivalent component.
1324 */
1325 typedef struct {
1326 uint16_t size; /**< Specify the software info size in 32-bit words */
1327 uint32_t swInfo[sa_MAX_SW_INFO_SIZE]; /**< Specify the software information for SA */
1328 } Sa_SWInfo_t;
1330 /**
1331 * @ingroup salld_api_macros
1332 * @brief sa_SWINFO_UPDATE_DEST_INFO is used to update the destination information within swInfo[2] at @ref Sa_SWInfo_t
1333 *
1334 * @details The application may want to deliver output packets to different queues for load balance.
1335 * This macro is used to update the destination queue and CPPI flow number in the Sa_SWInfo_t data structure
1336 * provided by Sa_chanSendData()
1337 *
1338 */
1339 #define sa_SWINFO_UPDATE_DEST_INFO(info, queueID, flowIndex) \
1340 { \
1341 (info[0]) |= 0x40000000L; \
1342 (info[2]) = ((queueID)) | (((flowIndex) & 0xFF) << 16) | ((info[2]) & 0xFF000000L); \
1343 } \
1345 /**
1346 * @ingroup salld_api_structures
1347 * @brief SA Command Label Parameter Information structure
1348 *
1349 * Data structure defines the updating information of parameters which may be updated within the
1350 * command label per packet.
1351 *
1352 */
1354 typedef struct {
1355 uint8_t index; /**< Specify the index of the starting 32-bit command word */
1356 uint8_t offset; /**< specify the offset to the parameter within the command word */
1357 uint8_t size; /**< Specify the size of parameter in bytes */
1359 } Sa_CmdLbParamInfo_t;
1361 /**
1362 * @defgroup DataSubModes Data Sub Operation Modes
1363 * @ingroup salld_api_constants
1364 * @{
1365 *
1366 * @name Data Sub Operation Modes
1367 *
1368 * Definition of the sub operation modes in Data mode.
1369 * Enhanced the sub modes to more general types of protocols such as WiMax.
1370 * Pleae refer to @ref Sa_DataModeConfigParams_t restrictions table
1371 * on supported IV, Salt and AAD sizes
1372 *
1373 */
1374 /*@{*/
1375 typedef enum {
1376 sa_DM_GEN = 0, /**< General operation mode */
1377 sa_DM_CCM, /**< CCM IPSEC */
1378 sa_DM_CCM_GEN, /**< CCM non IPSEC */
1379 sa_DM_GCM, /**< GCM IPSEC */
1380 sa_DM_GCM_GEN, /**< GCM non IPSEC */
1381 sa_DM_GMAC, /**< GMAC IPSec */
1382 sa_DM_GMAC_GEN, /**< GMAC non IPSec*/
1383 sa_DM_GMAC_AH /**< GMAC for IPSEC AH */
1384 } Sa_DM_subMode_e;
1385 /*@}*/
1386 /** @} */
1389 /**
1390 * @defgroup SALLDCmdLbUpdateVaildInfo SALLD Command Label Update Vaild Bit Definitions
1391 * @ingroup salld_api_constants
1392 * @{
1393 *
1394 * @name Command Label Update Valid Bit Definitions
1395 *
1396 * Bitmap definition of the validBitfield in Sa_CmdLbUpdateInfo_t.
1397 */
1398 /*@{*/
1399 /**
1400 * @def sa_CMDL_UPDATE_VALID_ENC
1401 * Control Info -- Encryption related information is valid
1402 */
1403 #define sa_CMDL_UPDATE_VALID_ENC 0x0001
1404 /**
1405 * @def sa_CMDL_UPDATE_VALID_AUTH
1406 * Control Info -- Authentication related information is valid
1407 */
1408 #define sa_CMDL_UPDATE_VALID_AUTH 0x0002
1409 /**
1410 * @def sa_CMDL_UPDATE_VALID_ENC_IV
1411 * Control Info -- Encryption IV is valid
1412 */
1413 #define sa_CMDL_UPDATE_VALID_ENC_IV 0x0004
1414 /**
1415 * @def sa_CMDL_UPDATE_VALID_AUTH_IV
1416 * Control Info -- Authentication IV valid
1417 */
1418 #define sa_CMDL_UPDATE_VALID_AUTH_IV 0x0008
1419 /**
1420 * @def sa_CMDL_UPDATE_VALID_AAD
1421 * Control Info -- AAD is valid
1422 */
1423 #define sa_CMDL_UPDATE_VALID_AAD 0x0010
1424 /**
1425 * @def sa_CMDL_UPDATE_VALID_AUX_KEY
1426 * Control Info -- CMAC-type Auxiliary key is valid
1427 */
1428 #define sa_CMDL_UPDATE_VALID_AUX_KEY 0x0020
1429 /**
1430 * @def sa_CMDL_UPDATE_VALID_PAYLOAD
1431 * Control Info -- Payload pending is valid such as GMAC mode
1432 */
1433 #define sa_CMDL_UPDATE_VALID_PAYLOAD 0x0040
1434 /**
1435 * @def sa_CMDL_UPDATE_VALID_ENC_SIZE
1436 * Control Info -- Second encryption size update is required, such as CCM mode
1437 */
1438 #define sa_CMDL_UPDATE_VALID_ENC_SIZE 0x0080
1439 /**
1440 * @def sa_CMDL_UPDATE_VALID_ENC_IV2
1441 * Control Info -- Second encryption IV update is required, such as CCM mode
1442 */
1443 #define sa_CMDL_UPDATE_VALID_ENC_IV2 0x0100
1444 /**
1445 * @def sa_CMDL_UPDATE_VALID_AUTH_SIZE
1446 * Control Info -- Second authentication size update is required, such as GMAC mode
1447 */
1448 #define sa_CMDL_UPDATE_VALID_AUTH_SIZE 0x0200
1450 /*@}*/
1451 /** @} */
1454 /**
1455 * @ingroup salld_api_structures
1456 * @brief SA Command Label Updating Information structure
1457 *
1458 * Data structure provides the information how to update the command label. The application can
1459 * use this information to update the command label per packet without invoking Sa_chanSendData() API.
1460 *
1461 */
1463 typedef struct {
1464 uint16_t validBitfield; /**< Specify the parameter valid Information as defined at @ref SALLDCmdLbUpdateVaildInfo */
1465 uint16_t subMode; /**< Specify the sub operation modes as defined at @ref DataSubModes */
1466 Sa_CmdLbParamInfo_t encSizeInfo; /**< Information used to update encryption size */
1467 Sa_CmdLbParamInfo_t encSizeInfo2; /**< Information used to update 2nd encryption size */
1468 Sa_CmdLbParamInfo_t encOffsetInfo; /**< Information used to update encryption offset */
1469 Sa_CmdLbParamInfo_t encIvInfo; /**< Information used to update encryption initialization vector */
1470 Sa_CmdLbParamInfo_t encIvInfo2; /**< Information used to update 2nd encryption initialization vector */
1471 Sa_CmdLbParamInfo_t aadInfo; /**< Information used to update AAD */
1472 Sa_CmdLbParamInfo_t payloadInfo; /**< Information used to update payload padding information */
1473 Sa_CmdLbParamInfo_t authSizeInfo; /**< Information used to update authentication size */
1474 Sa_CmdLbParamInfo_t authSizeInfo2; /**< Information used to update 2nd authentication size */
1475 Sa_CmdLbParamInfo_t authOffsetInfo; /**< Information used to update authentication offset */
1476 Sa_CmdLbParamInfo_t authIvInfo; /**< Information used to update authentication initialization vector */
1477 Sa_CmdLbParamInfo_t auxKeyInfo; /**< Information used to update auxiliary Key information */
1478 uint32_t auxKey[8]; /**< Contain auxiliary key1/key2 */
1479 } Sa_CmdLbUpdateInfo_t;
1481 /**
1482 * @ingroup salld_api_constants
1483 * @brief Define the maxmium size of the command label stored at cmdLbBuf of @ref Sa_CmdLabelInfo_t.
1484 */
1485 #define sa_MAX_CMDLB_SIZE 96
1487 /**
1488 * @ingroup salld_api_structures
1489 * @brief SA Command Label Information structure
1490 *
1491 * Data structure defines the SA-specific command label information used by SA to route packet
1492 * to sub-engines within SA. The command label information will be formatted by the SA LLD
1493 * based on the channel configuration parameters and the payload information as defined at
1494 * @ref Sa_PayloadInfo_t. The command label should be copied to the protocol-specific section
1495 * at the CPPI packet descriptor as provided through the CPPI LLD or equivalent component.
1496 *
1497 * @note: This structure is only used in Data Mode and the cmdLbBuf should be provided by the
1498 * caller.
1499 */
1500 typedef struct {
1501 uint16_t cmdLbSize; /**< Specify the command label size in bytes */
1502 uint8_t* cmdLbBuf; /**< Pointer to the buffer which contains the command labels
1503 The buffer should be allocated by the caller in Data
1504 Mode opeation and 4-byte alignment is required*/
1505 Sa_CmdLbUpdateInfo_t* cmdLbUpdateInfo; /**< Pointer to command label updating data structure, the command
1506 label updating information will be provided upon return if not
1507 NLL pointer */
1508 } Sa_CmdLabelInfo_t;
1510 /**
1511 * @ingroup salld_api_structures
1512 * @brief SA Payload Information structure
1513 *
1514 * Data structure providing the payload related information used to construct the
1515 * SA-specific command labels in data mode
1516 */
1517 typedef struct {
1518 uint8_t encOffset; /**< Specify the offset to the encrypted/decrypted data in the packet in bytes */
1519 uint8_t authOffset; /**< Specify the offset to the authenticated data in the packet in bytes */
1520 uint16_t encSize; /**< Specify the total number of bytes to be encrypted or decrypted */
1521 uint16_t authSize; /**< Specify the total number of bytes to be authenticated */
1522 uint8_t* encIV; /**< Contain the initialization vectors used in certain encryption modes.
1523 @note: IV should be specified here in GCM/GMAC/CCM mode */
1524 uint8_t* authIV; /**< Contain the initialization vectors used in certain authentication modes.*/
1525 uint8_t* aad; /**< Contain the additional authenticated data in GCM/GMAC/CCM modes */
1526 } Sa_PayloadInfo_t;
1528 /**
1529 * @ingroup salld_api_structures
1530 * @brief SA Rx Payload Information structure
1531 *
1532 * Data structure providing the miscellaneous header information of the received packets which is
1533 * required for the IPSEC post-processing function to patch the outer IP header when the inner IP
1534 * fragments have been reassembled by the hardware IP reassembly engine (RA) on the NSS Gen2 devices.
1535 *
1536 * @note: This structure should be provided at the Sa_chanReceiveData() call when the RA engine is enabled
1537 * for inner IP. If it is not provided, the IPSEC post-processing function will not be able to handle
1538 * inner IP reassembled packets correctly.
1539 */
1540 typedef struct {
1541 uint8_t ipOffset; /**< Specify the offset to the outer IP in the packet in bytes */
1542 uint8_t ipOffset2; /**< Specify the offset to the inner IP in the packet in bytes
1543 (0: indicates there is no inner IP) */
1544 } Sa_RxPayloadInfo_t;
1547 /**
1548 * @ingroup salld_api_structures
1549 * @brief SA IPSEC NAT-T structure
1550 *
1551 * Data structure defines the IPSEC NAT-T parameters used by @ref Sa_chanSendData() API to
1552 * construct the IPSEC NAT-T (UDP) header which resides in front of IPSEC ESP header.
1553 */
1554 typedef struct {
1555 uint16_t dstPort; /**< Specify the destination UDP port number */
1556 uint16_t srcPort; /**< Specify the source UDP port number */
1557 } Sa_ipsecNatTInfo_t;
1559 /**
1560 * @defgroup SALLDPktInfoValidBits SALLD Packet Info Valid Bit Definitions
1561 * @ingroup salld_api_constants
1562 * @{
1563 *
1564 * @name SALLD Packet Info Valid Bit Definitions
1565 *
1566 * Bitmap definition of the validBitMap in Sa_PktInfo_t.
1567 */
1568 /*@{*/
1569 /**
1570 * @def sa_PKT_INFO_VALID_PKT_ERR_CODE
1571 * - pktErrorCode is present
1572 */
1573 #define sa_PKT_INFO_VALID_PKT_ERR_CODE 0x0001
1574 /**
1575 * @def sa_PKT_INFO_VALID_SW_INFO
1576 * - swInfo is present
1577 */
1578 #define sa_PKT_INFO_VALID_SW_INFO 0x0002
1579 /**
1580 * @def sa_PKT_INFO_VALID_CMDLB_INFO
1581 * - cmdlb is present
1582 */
1583 #define sa_PKT_INFO_VALID_CMDLB_INFO 0x0004
1584 /**
1585 * @def sa_PKT_INFO_VALID_PAYLOAD_INFO
1586 * - payloadInfo is present
1587 */
1588 #define sa_PKT_INFO_VALID_PAYLOAD_INFO 0x0008
1589 /**
1590 * @def sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO
1591 * - natTInfo is present
1592 */
1593 #define sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO 0x0010
1594 /**
1595 * @def sa_PKT_INFO_VALID_RX_PAYLOAD_INFO
1596 * - rxPayloadInfo is present
1597 */
1598 #define sa_PKT_INFO_VALID_RX_PAYLOAD_INFO 0x0020
1601 /*@}*/
1602 /** @} */
1604 /**
1605 * @defgroup SALLDEspInfoTxRxValidBits SALLD ESP TxRx Info Valid Bit Definitions
1606 * @ingroup salld_api_constants
1607 * @{
1608 *
1609 * @name SALLD ESP TxRx Valid Bit Definitions
1610 *
1611 * Bitmap definition of the validBitMap in salldIpsecEspTxRxInfo_t.
1612 */
1613 /*@{*/
1614 /**
1615 * @def sa_ESP_TXRX_VALID_IPSEC_NAT_T_INFO
1616 * - espTxRx_natTInfo is present
1617 */
1618 #define sa_ESP_TXRX_VALID_IPSEC_NAT_T_INFO sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO
1619 /**
1620 * @def sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO
1621 * - rxPayloadInfo is present
1622 */
1623 #define sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO sa_PKT_INFO_VALID_RX_PAYLOAD_INFO
1625 /*@}*/
1626 /** @} */
1629 /**
1630 * @ingroup salld_api_structures
1631 * @brief IpSec ESP Data send/receive info structure
1632 *
1633 */
1634 typedef struct salldIpsecEspTxRxInfo_s {
1635 uint16_t validBitMap; /**< Specify which parameters are vaild as defined at @ref SALLDEspInfoTxRxValidBits */
1636 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
1637 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
1638 uint16_t encryptionBlockSize; /**< Specify the encryption block size
1639 1: Stream encryption and no alignment requirement
1640 4: AES-CTR or other stream-like encryption with 4-byte
1641 alignment
1642 block size: block encryption algorithm */
1643 Sa_ipsecNatTInfo_t natTInfo; /**< Specify the IPSEC NAT-T parameters, if natTInfo is present*/
1644 Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
1645 } salldIpsecEspTxRxInfo_t;
1647 /**
1648 * @ingroup salld_api_structures
1649 * @brief Packet Descriptor structure
1650 *
1651 * The packet may consist of one or more segments.
1652 * Several assumptions regarding the data organization among these segment(s) were made,
1653 * in compliance with requirements from the supported protocols. Below are a
1654 * list of assumptions imposed upon each packet with regard to their corresponding protocol.
1655 *
1656 * - IPSec
1657 * -# [Transmit] Segment containing IP Header must reserve approx 32 bytes of buffer space at the
1658 * beginning of the segment, to allow insertion of ESP/AH header after the IP header.
1659 * -# [Transmit] Final segment containing IP Datagram must reserve approx 32 bytes of buffer space at the
1660 * end of the segment, to allow insertion of ESP padding, ESP trailer and authentication tag.
1661 * -# [General] IP Header must be contiguous and in one segment.
1662 * - SRTP
1663 * -# [Transmit] Final segment containing SRTP payload must reserve approx 16 bytes of buffer space at the
1664 * end of the segment, to allow insertion of MKI and authentication tag.
1665 * -# [General] RTP Header must be contiguous in one segment.
1666 * -# [Receive] Total number of segments used to carry SRTP payload may not exceed 10.
1667 * - Air Cipher
1668 * -# No assumptions were made as data segments are untouched by the processing function.
1669 * - Data Mode
1670 * -# No assumptions were made as data segments are untouched by the processing function.
1671 *
1672 * @note Elements in the packet descriptor structure may change, after each protocol specific processing.
1673 */
1674 typedef struct {
1675 int32_t size; /**< packet length */
1676 uint16_t payloadOffset; /**< offset from base of the packet to the header
1677 of protocol per the following list:
1678 IPSEC ESP/AH: IP header
1679 IPSEC ESP(Output): ESP Header
1680 SRTP: RTP header
1681 SRTCP: RTCP header
1682 3GPP Air Ciphering: PDU header */
1683 uint16_t payloadLen; /**< length of the payload starting from payloadOffset to the end of the protocol */
1684 uint16_t nSegments; /**< number of segments */
1685 void** segments; /**< data segments */
1686 uint16_t *segUsedSizes; /**< pointer to segment used size array */
1687 uint16_t *segAllocSizes; /**< pointer to segment allocated size array */
1688 } Sa_PktDesc_t; /* base class */
1690 /**
1691 * @ingroup salld_api_structures
1692 * @brief Packet Information structure
1693 *
1694 * Data structure defines the SALLD input/output packet formats
1695 *
1696 */
1697 typedef struct {
1698 Sa_PktDesc_t pktDesc; /**< Specify packet descriptor */
1699 uint16_t validBitMap; /**< Specify which parameters are vaild as defined at @ref SALLDPktInfoValidBits */
1700 uint16_t pktErrCode; /**< Specify the error code of the received packet as defined at Sa_PktErr_t */
1701 Sa_SWInfo_t swInfo; /**< Specify the software information required by SA */
1702 Sa_CmdLabelInfo_t cmdlb; /**< Specify the command label in data mode */
1703 Sa_PayloadInfo_t payloadInfo;/**< Specify the payload information in data mode */
1704 Sa_ipsecNatTInfo_t natTInfo; /**< Specify the IPSEC NAT-T parameters */
1705 Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
1706 } Sa_PktInfo_t;
1708 /**
1709 * @defgroup SALLDSrtpKeyReqInfo SALLD SRTP Key Request Info Control Bit Definitions
1710 * @ingroup salld_api_constants
1711 * @{
1712 *
1713 * @name SRTP Key Request Info Control Bit Definitions
1714 *
1715 * Bitmap definition of the ctrlBitfield in Sa_SrtpKeyRequest_t.
1716 */
1717 /*@{*/
1718 /**
1719 * @def sa_SRTP_KEY_REQUEST_KEY_TYPE_MKI
1720 * Control Info -- Set: MKI Key
1721 * Clear: From-To Key
1722 */
1723 #define sa_SRTP_KEY_REQUEST_KEY_TYPE_MKI 0x0001
1724 /**
1725 * @def sa_SRTP_KEY_REQUEST_TX_KEY
1726 * Control Info -- Request Tx key
1727 */
1728 #define sa_SRTP_KEY_REQUEST_TX_KEY 0x0002
1729 /**
1730 * @def sa_SRTP_KEY_REQUEST_RX_KEY
1731 * Control Info -- Request Rx key
1732 */
1733 #define sa_SRTP_KEY_REQUEST_RX_KEY 0x0004
1734 /**
1735 * @def sa_SRTP_KEY_REQUEST_MKI_VALID
1736 * Control Info -- MKI VALUE included
1737 */
1738 #define sa_SRTP_KEY_REQUEST_MKI_VALID 0x0008
1740 /*@}*/
1741 /** @} */
1743 /**
1744 * @ingroup salld_api_structures
1745 * @brief SRTP Key Request structure
1746 *
1747 * Data structure defines the key request information for SRTP
1748 *
1749 */
1750 typedef struct {
1751 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information
1752 as defined at @ref SALLDSrtpKeyReqInfo */
1753 uint32_t mki; /**< Specify the MKI value of the MKI keys */
1754 } Sa_SrtpKeyRequest_t;
1756 /**
1757 * @ingroup salld_api_structures
1758 * @brief Key Request structure
1759 *
1760 * Data structure defines the key request information for all supported protocols
1761 *
1762 */
1763 typedef struct {
1764 union {
1765 Sa_SrtpKeyRequest_t srtp; /**< Specify the key request parameters for SRTP */
1766 } params; /**< Contain the protocol-specific key request information */
1767 } Sa_KeyRequest_t;
1769 /**
1770 * @ingroup salld_api_structures
1771 * @brief Security Context Request Information structure
1772 *
1773 * SASS is equipped with context cache module to auto-fetch security context
1774 * from external memory. This module is essential to allow any number of simultaneous
1775 * security connections by caching only limited (64) contexts on-chip and fetching other
1776 * contexts as and when required for processing.
1777 *
1778 * In order to facilitate fast retrieval for performance critical connections such as IPSEC channels,
1779 * context cache module allows two tier of security connections. First tier has permanent
1780 * residence within Context cache RAM for fast retrieval and is never evicted automatically
1781 * by context cache module. Second tier connections are kept as long as space is available within
1782 * context cache RAM; new fetch request may automatically evict the context of the second tier connections
1783 * into external memory to allow free space.
1784 *
1785 * The following data structure defines the parameters for the security context request.
1786 * The 15-bit security context ID, of which LSB 4-bits act as cache set select, and
1787 * its corresponding context buffer, which contains the protocol-specific security parameters
1788 * used by the LLD and sub-engines within SA, should be maintained across multiple DSP cores.
1789 * They are multi-core resources and should be managed by the application.
1790 *
1791 * The security context IDs and buffers can be managed across mult-cores or be pre-allocated for
1792 * each core or each security channel. The security context buffer should be 16-byte aligned at least
1793 * and it should be cache-line aligned if it is allocated at cacheable memory. It is recommended to
1794 * maintain the security context buffers in the following three lists:
1795 *
1796 * @verbatim
1797 Allocated: The buffer and its corresponding ID have been allocated to the SA
1798 LLD through *ScAlloc API and they are owned by SA.
1799 Pending Free: The buffer and its corresponding ID has been released from the
1800 SA LLD through *ScFree API. However, they are still owned by
1801 SA until the security context tear-down procedure is complete.
1802 The API Sa_isScBufFree should be used to check
1803 whether the buffer is free
1804 Free: The buffer and its corresonding ID are owned by the application.
1805 @endverbatim
1806 *
1807 * @note There are only up to three first tier contexts allowed for each cache set.
1808 *
1809 * @note It is highly recommended to place the security context buffers at non-cacheable memory
1810 * since they are accessed and maintained by the SA sub-system primarily
1811 *
1812 * @note The application can manage the security context buffers and IDs as
1813 * two seperate resources or a single resource pair. The only
1814 * requirement is that the security context ID cannot be re-used until
1815 * its corresponding security context buffer is free.
1816 * The application may perform periodic checks to move buffers from the
1817 * Pending Free list to the Free list or perform checks only when new
1818 * buffers are requested by the SA LLD.
1819 */
1820 typedef struct {
1821 uint16_t scSize; /**< Specify the size of the required security context */
1822 uint16_t scID; /**< Security Context ID specified by the application */
1823 uint8_t* scBuf; /**< Security Context Buffer provided by the application
1824 (16-byte alignment required) */
1825 } Sa_ScReqInfo_t;
1827 /**
1828 * @def sa_SC_ID_MASK
1829 * Define security context ID mask.
1830 */
1831 #define sa_SC_ID_MASK 0x7FFF
1833 /**
1834 * @def sa_SC_IND_PERMANENT
1835 * Indicate that the corresponding security context is permanent
1836 */
1837 #define sa_SC_IND_PERMANENT 0x8000
1840 /**
1841 * @defgroup saScMaxSize Security Context maximum size requirements
1842 * @ingroup salld_api_constants
1843 * @{
1844 *
1845 * @name Security Context maximum size
1846 *
1847 * Define Security Context maximum size requirements.
1848 */
1849 /* @{ */
1851 /**
1852 * @def sa_IPSEC_TX_MAX_SC_SIZE
1853 * The maximum security context size required for IPSEC Tx channel
1854 */
1855 #define sa_IPSEC_TX_MAX_SC_SIZE 288
1858 /**
1859 * @def sa_IPSEC_RX_MAX_SC_SIZE
1860 * The maximum security context size required for IPSEC Rx channel
1861 *
1862 * Note: The maxmium IPSEC Rx channel security context includes the extra 128 bytes used by
1863 * large replay window when the replay window size exceeds 128.
1864 */
1865 #define sa_IPSEC_RX_MAX_SC_SIZE 448
1866 #define sa_IPSEC_RX_MAX_SC_SIZE_SM_REPLAY_WINDOW 320
1868 /**
1869 * @def sa_SRTP_TX_MAX_SC_SIZE
1870 * The maximum security context size required for SRTP Tx channel
1871 */
1872 #define sa_SRTP_TX_MAX_SC_SIZE 224
1875 /**
1876 * @def sa_SRTP_RX_MAX_SC_SIZE
1877 * The maximum security context size required for SRTP Rx channel
1878 */
1879 #define sa_SRTP_RX_MAX_SC_SIZE 288
1881 /**
1882 * @def sa_AC_MAX_SC_SIZE
1883 * The maximum security context size required for Air Ciphering channel
1884 */
1885 #define sa_AC_MAX_SC_SIZE 288
1887 /**
1888 * @def sa_DATA_MODE_MAX_SC_SIZE
1889 * The maximum security context size required for Data Mode channel
1890 */
1891 #define sa_DATA_MODE_MAX_SC_SIZE 256
1893 /**
1894 * @def sa_MAX_SC_SIZE
1895 * Define the maxmium size of the security context buffer defined at @ref Sa_ScReqInfo_t.
1896 */
1897 #define sa_MAX_SC_SIZE 448
1899 /* @} */
1900 /** @} */
1902 /**
1903 * @ingroup salld_api_constants
1904 * @brief Define the maxmium replay window size supported by SASS.
1905 */
1906 #define sa_MAX_REPLAY_WINDOW_SIZE 1024
1907 #define sa_MAX_REPLAY_WINDOW_SIZE_GEN1 128 /* first generation SASS */
1908 #define sa_MAX_REPLAY_WINDOW_SIZE_GEN2 1024 /* second generation SASS */
1910 /**
1911 * @ingroup salld_api_structures
1912 * @brief SALLD Replay Window Context
1913 *
1914 * This structure defines the replay window context which reprenets the snapshot of
1915 * SASS replay windows.
1916 */
1918 typedef struct Sa_Replay_Cxt_tag
1919 {
1920 uint32_t winMask[sa_MAX_REPLAY_WINDOW_SIZE/32]; /**< Bitmask Array:w0.b0, w0.b1, ... w1.b0, w0.b2 ...
1921 1:packet received
1922 0:packet not received*/
1923 uint32_t winBaseHi; /**< Upper 32-bit of win_base when ESN is enabled */
1924 uint32_t winBase; /**< Lower 32-bit of win_base which represents the sequence number of
1925 the oldest packet received */
1926 } Sa_Replay_Cxt_t;
1928 /**
1929 * @defgroup SALLDStatsCtrlBit SALLD Statistics Query Control Bit Definitions
1930 * @ingroup salld_api_constants
1931 * @{
1932 *
1933 * @name SALLD Statistics Query Control Bit Definitions
1934 * Bitmap definition of the control flags in Sa_chanGetStats() API.
1935 */
1936 /*@{*/
1937 /**
1938 * @def sa_STATS_QUERY_FLAG_CLEAR
1939 * Control Info -- Clear some statistics after they are reported
1940 */
1941 #define sa_STATS_QUERY_FLAG_CLEAR 0x0001
1942 /**
1943 * @def sa_STATS_QUERY_FLAG_TRIG
1944 * Control Info -- Inform the SA Sub-system to provide statistics
1945 */
1946 #define sa_STATS_QUERY_FLAG_TRIG 0x0002
1947 /**
1948 * @def sa_STATS_QUERY_FLAG_NOW
1949 * Control Info -- Request the SA LLD to provide the latest available statistics
1950 * If the bit is not set, the SA LLD will return sa_ERR_STATS_UNAVAIL if the
1951 * latest statistics is not available
1952 */
1953 #define sa_STATS_QUERY_FLAG_NOW 0x0004
1954 /*@}*/
1955 /** @} */
1957 /**
1958 * @ingroup salld_api_structures
1959 * @brief SALLD SRTP Statistics Structure
1960 *
1961 * This structure defines the SRTP-specific statistics provided upon request
1962 * with salldChanStats().
1963 */
1964 typedef struct {
1965 uint32_t replayOld; /**< Number of replay failures with old packets */
1966 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
1967 uint32_t authFail; /**< Number of Authentication failures */
1968 uint32_t txROC; /**< Tx Roll-over Counter (32-bits) */
1969 uint32_t rxROC; /**< RX Roll-Over Counter (32 bits) */
1970 uint16_t txRekey; /**< Number of times re-keying happened in Tx */
1971 uint16_t rxRekey; /**< Number of times re-keying happened in Rx */
1972 uint16_t pktEncHi; /**< Total Number of Packets encrypted with this key (48-bits) Upper 16 bits */
1973 uint32_t pktEncLo; /**< Total Number of Packets encrypted with this key (48-bits) Lower 32 bits */
1974 uint16_t pktDecHi; /**< Total Number of Packets decrypted with this key (48-bits) Upper 16 bits */
1975 uint32_t pktDecLo; /**< Total Number of Packets decrypted with this key (48-bits) Lower 32 bits */
1976 } Sa_SrtpStats_t;
1978 /**
1979 * @ingroup salld_api_structures
1980 * @brief SALLD SRTCP Statistics Structure
1981 *
1982 * This structure defines the SRTCP-specific statistics provided upon request
1983 * with salldChanStats().
1984 */
1985 typedef struct {
1986 uint32_t replayOld; /**< Number of replay failures with old packets */
1987 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
1988 uint32_t authFail; /**< Number of Authentication failures */
1989 uint16_t txRekey; /**< Number of times re-keying happened in Tx */
1990 uint16_t rxRekey; /**< Number of times re-keying happened in Rx */
1991 uint32_t pktEnc; /**< Total Number of Packets encrypted with this key (32-bits) */
1992 uint32_t pktDec; /**< Total Number of Packets decrypted with this key (32-bits) */
1993 } Sa_SrtcpStats_t;
1995 /**
1996 * @ingroup salld_api_structures
1997 * @brief SALLD IPSEC Statistics Structure
1998 *
1999 * This structure defines the IPSEC-specific statistics provided upon request
2000 * with salldChanStats().
2001 */
2002 typedef struct {
2003 Sa_Replay_Cxt_t replayCxt; /**< Snapshot of the replay context */
2004 uint32_t replayOld; /**< Number of replay failures with old packets */
2005 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2006 uint32_t authFail; /**< Number of Authentication failures */
2007 uint32_t txRollover; /**< Number of Tx packets dropped due to rollover error, i.e. the sequence number exceed its limit (0xFFFFFFFF) */
2008 uint32_t txESN; /**< Tx ESN (32-bits) */
2009 uint32_t txSN; /**< Sequence Number (32-bits) of the last transmitted packet */
2010 uint32_t rxESN; /**< RX ESN (32 bits) */
2011 uint32_t pktEncHi; /**< Total Number of Packets encrypted with this key (64-bits) Upper 32 bits */
2012 uint32_t pktEncLo; /**< Total Number of Packets encrypted with this key (64-bits) Lower 32 bits */
2013 uint32_t pktDecHi; /**< Total Number of Packets decrypted with this key (64-bits) Upper 32 bits */
2014 uint32_t pktDecLo; /**< Total Number of Packets decrypted with this key (64-bits) Lower 32 bits */
2015 uint32_t txByteCountHi; /**< Total bytes processed by SA on TX (64-bits) Upper 32 bits */
2016 uint32_t txByteCountLo; /**< Total bytes processed by SA on TX (64-bits) Lower 32 bits */
2017 uint32_t rxByteCountHi; /**< Total bytes processed by SA on RX (64-bits) Upper 32 bits */
2018 uint32_t rxByteCountLo; /**< Total bytes processed by SA on RX (64-bits) Lower 32 bits */
2019 } Sa_IpsecStats_t;
2021 /**
2022 * @ingroup salld_api_structures
2023 * @brief SALLD Air Ciphering Statistics Structure
2024 *
2025 * This structure defines the Air Ciphering-specific statistics provided upon request
2026 * with salldChanStats().
2027 */
2028 typedef struct {
2029 uint32_t authFail; /**< Number of Authentication failures */
2030 uint32_t toAirCountC; /**< To-Air Count-C (32-bits) */
2031 uint32_t fromAirCountC; /**< From-Air Count-C (32-bits) */
2032 uint32_t pktToAirHi; /**< Total Number of To-Air Packets (64-bits) Upper 32 bits */
2033 uint32_t pktToAirLo; /**< Total Number of To-Air Packets (64-bits) Lower 32 bits */
2034 uint32_t pktFromAirHi; /**< Total Number of From-Air Packets (64-bits) Upper 32 bits */
2035 uint32_t pktFromAirLo; /**< Total Number of From-Air Packets (64-bits) Lower 32 bits */
2036 } Sa_AcStats_t;
2038 /**
2039 * @ingroup salld_api_structures
2040 * @brief SALLD Data Mode Statistics Structure
2041 *
2042 * This structure defines the Data Mode statistics provided upon request
2043 * with salldChanStats().
2044 */
2045 typedef struct {
2046 uint32_t pktHi; /**< Total Number of processed Packets (64-bits) Upper 32 bits */
2047 uint32_t pktLo; /**< Total Number of processed Packets (64-bits) Lower 32 bits */
2048 } Sa_DataModeStats_t;
2050 /**
2051 * @ingroup salld_api_structures
2052 * @brief SALLD Statistics Structure
2053 *
2054 * This structure defines the protocol-specific statistics provided upon request
2055 * with salld_chanGetStats().
2056 */
2057 typedef union {
2058 Sa_SrtpStats_t srtp; /**< SRTP-specific channel statistics */
2059 Sa_SrtcpStats_t srtcp; /**< SRTCP-specific channel statistics */
2060 Sa_IpsecStats_t ipsec; /**< IPSEC-specific channel statistics */
2061 Sa_AcStats_t ac; /**< 3GPP Air Ciphering-specific channel statistics */
2062 Sa_DataModeStats_t data; /**< Data Mode channel statistics */
2063 } Sa_Stats_t;
2065 /**
2066 * @ingroup salld_api_structures
2067 * @brief Specification of Sa_Handle
2068 * The Sa_Handle is used to identify a SALLD system instance
2069 */
2070 typedef void* Sa_Handle;
2072 /**
2073 * @ingroup salld_api_structures
2074 * @brief The SALLD Call-out function table
2075 *
2076 * The SALLD software module requires a set of call-out functions to report debug information,
2077 * request and free system resources, and etc. All the call-out functions should be implemented
2078 * by the application and provided to the SALLD at @ref Sa_create
2079 *
2080 */
2081 typedef struct Sa_CallOutFuns_s {
2083 /**
2084 * @brief A callout to the system code's debug and exception handling function. This is a function
2085 * pointer and must point to a valid function which meets the API requirements.
2086 *
2087 * @param[in] handle SALLD channel instance identifier.
2088 * @param[in] msgType Specify how serious the debug message is as defined at @ref salldDebugMessageTypes.
2089 * @param[in] msgCode Specify the message code as defined at @ref salldDebugMessageCodes.
2090 * @param[in] msgLength Specify the length of the message supporting data.
2091 * @param[in] msgData Pointer to the message supporting data.
2092 */
2093 void (*DebugTrace) (Sa_ChanHandle handle, uint16_t msgType, uint16_t msgCode,
2094 uint16_t msgLength, uint16_t *msgData);
2095 /**
2096 * @brief Callout to externally supplied system to request a new security key. This function may be triggered
2097 * by either the Sa_chanSendData() or Sa_chanReceiveData() APIs. The application should call the
2098 * Sa_chanControl() API to pass the new key when it is available.
2099 * This is a function pointer and must point to a valid function which meets the API requirements.
2100 *
2101 * @param[in] handle SALLD channel instance identifier.
2102 * @param[in] keyReq Pointer to SALLD key Request structure.
2103 *
2104 * @sa Sa_KeyRequest_t
2105 *
2106 */
2107 void (*ChanKeyRequest) (Sa_ChanHandle handle, Sa_KeyRequest_t* keyReq);
2109 /**
2110 * @brief Callout to externally supplied system to allocate the security context with the specified size.
2111 * This function must be implemented as a simple non-blocking function.
2112 * This is a function pointer and must point to a valid function which meets the API requirements.
2113 *
2114 * @param[in] handle SALLD channel instance identifier.
2115 * @param[in] scReqInfo Pointer to SALLD security context Request Information structure.
2116 *
2117 * @sa Sa_ScReqInfo_t
2118 *
2119 * @note:Both the base address and size of the security context buffer should be cache-line and csche-line size
2120 * aligned if it is allocated at cacheable memory, otherwise, the base address should be 16-byte aligned.
2121 * It is highly recommended to place the security context buffers at non-cacheable memory
2122 * since they are accessed and maintained by the SA sub-system primarily
2123 */
2124 void (*ScAlloc) (Sa_ChanHandle handle, Sa_ScReqInfo_t* scReqInfo);
2126 /**
2127 * @brief Callout to externally supplied system to release the security context with the specified ID.
2128 * This function must be implemented as a simple non-blocking function.
2129 * This is a function pointer and must point to a valid function which meets the API requirements.
2130 *
2131 * @param[in] handle SALLD channel instance identifier.
2132 * @param[in] scID Security Context ID
2133 *
2134 * @note The security context buffer is only released from the SA LLD and is still owned by SA.
2135 * It should be maintained at the Pending Free list until it is freed by SA.
2136 * Use API @ref Sa_isScBufFree() to check its status.
2137 *
2138 */
2139 void (*ScFree) (Sa_ChanHandle handle, uint16_t scID);
2141 /**
2142 * @brief Callout to externally supplied system to register the security channel with its software
2143 * routing information to be programmed into the PASS lookup table in the from-Network direction.
2144 * It may be triggered by the Sa_chanControl(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2145 * This is a function pointer and must point to a valid function which meets the API requirements.
2146 *
2147 * @param[in] handle SALLD channel instance identifier.
2148 * @param[in] chanSwInfo Pointer to SALLD software routing information structure.
2149 *
2150 * @sa Sa_SWInfo_t
2151 *
2152 */
2153 void (*ChanRegister) (Sa_ChanHandle handle, Sa_SWInfo_t* chanSwInfo);
2155 /**
2156 * @brief Callout to externally supplied system to un-register the security channel with its software
2157 * routing information to be removed from the PASS lookup tables. It may be triggered by
2158 * the sSa_chanClose(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2159 * This is a function pointer and must point to a valid function which meets the API requirements.
2160 *
2161 * @param[in] handle SALLD channel instance identifier.
2162 * @param[in] chanSwInfo Pointer to SALLD software routing information structure.
2163 *
2164 * @sa Sa_SWInfo_t
2165 *
2166 */
2167 void (*ChanUnRegister) (Sa_ChanHandle handle, Sa_SWInfo_t* chanSwInfo);
2169 /**
2170 * @brief Callout to externally supplied system to send an Null packet to the SA sub-system.
2171 * The null packet is used to evict and/or tear down the security context associated with the channel.
2172 * It may be triggered by the Sa_chanClose(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2173 * This is a function pointer and must point to a valid function which meets the API requirements.
2174 *
2175 * @param[in] handle SALLD channel instance identifier.
2176 * @param[in] pktInfo Pointer to the packet info structure.
2177 *
2178 * @sa Sa_PktInfo_t
2179 *
2180 */
2181 void (*ChanSendNullPkt) (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo);
2183 } Sa_CallOutFuncs_t;
2185 /**
2186 * @ingroup salld_api_structures
2187 * @brief SA Size Configuration Structure
2188 *
2189 * @details The module is configured at run time with a maximum number of channels supported.
2190 */
2191 typedef struct {
2192 uint16_t nMaxChan; /**< Maximum number of channels supported */
2193 int cacheLineSize; /**< Specify the size of cache line of the memory where the system buffer will reside
2194 @note cacheLineSize should be the larger of cache line sizes amoung mixed processors */
2195 uint16_t ctrlBitMap; /**< Various configuration information as specified at @ref saSizeConfigCtrlBit */
2196 } Sa_SizeCfg_t;
2198 /**
2199 * @defgroup saEngSelMode SA Engine Selector Algorithms
2200 * @ingroup salld_api_constants
2201 * @{
2202 *
2203 * @name SA Engine Selector Algorithms
2204 *
2205 * There are two sets of IPSEC processing engines at the second generation SASS.
2206 * During SA initialization, user may configure IPSEC processing engine set
2207 * selection algorithm to be used during channel creation by setting the variable
2208 * engSelMode to the following values:
2209 *
2210 * - 0 (Load balanced)
2211 * -# SA will select the set of engines with lower channel utility
2212 * - 1 (Channel-based Round Robin selection)
2213 * -# SA will use each set of engines interleaved in order for each channel created
2214 * - 2 (User Select)
2215 * -# User will specify engine set to use when creating new channel
2216 */
2217 /*@{*/
2219 typedef enum {
2220 sa_EngSelMode_LOADBALANCED = 0,
2221 sa_EngSelMode_ROUNDROBIN,
2222 sa_EngSelMode_USERSPECIFIED
2223 } Sa_EngSelMode_e;
2224 /*@}*/
2225 /** @} */
2227 /**
2228 * @ingroup salld_api_structures
2229 * @brief SALLD Configuration structure
2230 *
2231 * Data structure providing configuration information in @ref Sa_create()
2232 *
2233 */
2234 typedef struct {
2235 uint32_t ID; /**< User specified module ID */
2236 uint32_t baseAddr; /**< Specify the SASS base address */
2237 Sa_CallOutFuncs_t *callTable; /**< Pointer to call-out function Table */
2238 Sa_EngSelMode_e engSelMode; /**< User specified authentication/encryption
2239 engine set selection mode */
2240 void* intBuf; /**< Pointer to an arbitrary internal buffer of at least @ref sa_MAX_SC_SIZE bytes
2241 for temporary key storage during air ciphering security
2242 context construction, The buffer needs an alignment of 4 bytes */
2243 Sa_SizeCfg_t *sizeConfig; /**< SALLD memory allocation requirement structure */
2244 void *instPoolBaseAddr; /**< Base address of the global shared memory pool from which global
2245 LLD instance & channel instance memory is allocated.*/
2246 void *scPoolBaseAddr; /**< Base address of the global shared memory pool from which SA
2247 security context memory is allocated. This is a DMA\92able memory */
2248 } Sa_Config_t;
2250 /**
2251 * @ingroup salld_api_structures
2252 * @brief SALLD SRTP System Statistics Structure
2253 *
2254 * This structure defines the SRTP-specific system statistics provided upon request
2255 * with Sa_getSysStats().
2256 */
2257 typedef struct {
2258 uint32_t replayOld; /**< Number of replay failures with old packets */
2259 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2260 uint32_t authFail; /**< Number of Authentication failures */
2261 uint32_t pktEncHi; /**< Total Number of Packets encrypted Upper 32 bits */
2262 uint32_t pktEncLo; /**< Total Number of Packets encrypted Lower 32 bits */
2263 uint32_t pktDecHi; /**< Total Number of Packets decrypted Upper 32 bits */
2264 uint32_t pktDecLo; /**< Total Number of Packets decrypted Lower 32 bits */
2265 } Sa_SrtpSysStats_t;
2267 /**
2268 * @ingroup salld_api_structures
2269 * @brief SALLD IPSEC System Statistics Structure
2270 *
2271 * This structure defines the IPSEC-specific system statistics provided upon request
2272 * with Sa_getSysStats().
2273 */
2274 typedef struct {
2275 uint32_t replayOld; /**< Number of replay failures with old packets */
2276 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2277 uint32_t authFail; /**< Number of Authentication failures */
2278 uint32_t pktEncHi; /**< Total Number of Packets encrypted Upper 32 bits */
2279 uint32_t pktEncLo; /**< Total Number of Packets encrypted Lower 32 bits */
2280 uint32_t pktDecHi; /**< Total Number of Packets decrypted Upper 32 bits */
2281 uint32_t pktDecLo; /**< Total Number of Packets decrypted Lower 32 bits */
2282 } Sa_IpsecSysStats_t;
2284 /**
2285 * @ingroup salld_api_structures
2286 * @brief SALLD Air Ciphering System Statistics Structure
2287 *
2288 * This structure defines the Air Ciphering-specific systrem statistics provided upon request
2289 * with Sa_getSysStats().
2290 */
2291 typedef struct {
2292 uint32_t authFail; /**< Number of Authentication failures */
2293 uint32_t pktToAirHi; /**< Total Number of To-Air Packets Upper 32 bits */
2294 uint32_t pktToAirLo; /**< Total Number of To-Air Packets Lower 32 bits */
2295 uint32_t pktFromAirHi; /**< Total Number of From-Air Packets Upper 32 bits */
2296 uint32_t pktFromAirLo; /**< Total Number of From-Air Packets Lower 32 bits */
2297 } Sa_AcSysStats_t;
2299 /**
2300 * @ingroup salld_api_structures
2301 * @brief SALLD Error System Statistics Structure
2302 *
2303 * This structure defines the SA error system statistics provided upon request
2304 * with Sa_getSysStats().
2305 */
2306 typedef struct {
2307 uint32_t errNoMem; /**< Number of packets dropped due to lack of PDSP instance memory */
2308 uint32_t errCtx; /**< Number of packets dropped due to security context error */
2309 uint32_t errEngine; /**< Number of packets dropped due to SA processing engine error */
2310 uint32_t errProto; /**< Number of packets dropped due to protocol error such as inavlid IP version */
2311 } Sa_ErrorSysStats_t;
2313 /**
2314 * @ingroup salld_api_structures
2315 * @brief SALLD Statistics Structure
2316 *
2317 * This structure defines the system statistics provided upon request
2318 * with @ref Sa_getSysStats().
2319 */
2320 typedef struct Sa_SysStats_s {
2321 Sa_ErrorSysStats_t err; /**< System Error statistics */
2322 Sa_IpsecSysStats_t esp; /**< IPSEC(ESP)-specific system statistics */
2323 Sa_IpsecSysStats_t ah; /**< IPSEC(AH)-specific system statistics */
2324 Sa_SrtpSysStats_t srtp; /**< SRTP-specific system statistics */
2325 Sa_AcSysStats_t ac; /**< 3GPP Air Ciphering-specific system statistics */
2326 } Sa_SysStats_t;
2328 /**
2329 * @defgroup PkaOpTypes PKA Arithmetic Operation Types
2330 * @ingroup salld_api_constants
2331 * @{
2332 *
2333 * @name PKA Arithmetic Operation Types
2334 *
2335 * Definition of PKA Arithmetic Operation Types
2336 * Parameter operation of Sa_PkaReqInfo_t should be set to one of these types.
2337 */
2338 /*@{*/
2339 typedef enum {
2340 sa_PKA_OP_ADD = 0, /**< Large Vector Addition (A+B)*/
2341 sa_PKA_OP_SUB, /**< Large Vector Subtraction (A-B)*/
2342 sa_PKA_OP_MUL, /**< Large Vector Mutiplication (A*B)*/
2343 sa_PKA_OP_DIV, /**< Large Vector Division (A/B)*/
2344 sa_PKA_OP_RSHIFT, /**< Large Vector Shift Right (A>>shiftval) */
2345 sa_PKA_OP_LSHIFT, /**< Large Vector Shift Left (A<<shiftval)*/
2346 sa_PKA_OP_COMP, /**< Large Vector Comparison (A?B)*/
2347 sa_PKA_OP_COPY, /**< Large Vector Copy (A->C)*/
2348 sa_PKA_OP_EXP2, /**< Large Vector Exponentiation (Cexp(A)mod(B))(2-bit ACT) */
2349 sa_PKA_OP_EXP4 /**< Large Vector Exponentiation (Cexp(A)mod(B))(4-bit ACT) */
2350 } Sa_PkaOpTypes_t;
2351 /*@}*/
2352 /** @} */
2354 /**
2355 * @defgroup PkaCompResults PKA Comparison Results
2356 * @ingroup salld_api_constants
2357 * @{
2358 *
2359 * @name PKA Comparison Results
2360 *
2361 * Definition of PKA Comparsion Result from SALLD API @ref Sa_pkaOperation
2362 */
2363 /*@{*/
2364 typedef enum {
2365 sa_PKA_COMP_AEQB = 1, /**< A=B */
2366 sa_PKA_COMP_AINFB = 2, /**< A<B */
2367 sa_PKA_COMP_ASUPB = 4 /**< A>B */
2368 } Sa_PkaCompResults_t;
2369 /*@}*/
2370 /** @} */
2372 /*
2373 * @ingroup salld_api_constants
2374 * @brief Define the maxmium size of the PKA operands in 32-bit words.
2375 */
2376 #define sa_MAX_PKA_OPERAND_SIZE 128 /**< 4k-bits or 128 32-bit words */
2377 #define sa_MAX_PKA_OPERAND_SIZE_EXP4 64 /**< 2k-bits or 64 32-bit words */
2379 /**
2380 * @ingroup salld_api_structures
2381 * @brief SALLD PKA Operation Request Structure
2382 *
2383 * This structure defines PKA request information which is used to perform the large
2384 * vector arithmetic operations.
2385 *
2386 * @par
2387 *
2388 * Restrictions of input parameters:
2389 * - Add: Alength, Blength > 0
2390 * - Subtract: Alength, Blength > 0; Alength >= Blength
2391 * - Multiply: Alength, Blength > 0
2392 * - Divide:
2393 * - Alength, Blength > 1
2394 * - Alength >= Blength
2395 * - Boperand cannot be zero
2396 * - Most significant word of Boperand can not be zero
2397 * - Right/Left Shift: Alength > 0
2398 * - Compare: Alength, Blength > 0; Alength = Blength
2399 * - Copy: Alength > 0
2400 * - Exponentitation (2-bit/4-bit ACT):
2401 * - Alength > 0
2402 * - Blength > 1
2403 * - Blength >= Alength
2404 * - Aoperand cannot be zero
2405 * - Coperand cannot be zero
2406 * - Boperand is odd (least significant bit set to 1)
2407 * - Most significant word of Boperand can not be zero
2408 * - Boperand > Coperand
2409 */
2410 typedef struct {
2411 Sa_PkaOpTypes_t operation; /**< Specify the arithmetic operation as defined at salldPkaOpTypes_t */
2412 Sa_PkaCompResults_t cmpResult; /**< Store the comparsion result */
2413 uint16_t numShiftBits; /**< Specify number of bits in shift operation */
2414 uint16_t oprandSize[2]; /**< Specify the size of operands (A, B(C))in 32-bit words */
2415 uint16_t resultSize; /**< Specify the size of result in 32-bit words */
2416 uint16_t remSize; /**< Specify the size of reminder in 32-bit words */
2417 uint32_t* oprandPtr[3]; /**< Pointers to up to 3 operand (A,B and C) buffers*/
2418 uint32_t* remPtr; /**< Pointer to the buffer to store the reminder */
2419 uint32_t* resultPtr; /**< Pointer to the buffer to store the operation result */
2420 } Sa_PkaReqInfo_t;
2422 /**
2423 * @defgroup SALLDRngConfigCtrlInfo SALLD RNG Configuration Control Info Bit Definitions
2424 * @ingroup salld_api_constants
2425 * @{
2426 *
2427 * @name RNG Configuration Control Info Bit Definitions
2428 *
2429 * Bitmap definition of the ctrlBitfield in @ref Sa_RngConfigParams_t.
2430 */
2431 /*@{*/
2432 /**
2433 * @def sa_RNG_CTRL_REINIT
2434 * Control Info -- Set: Force re-initialization
2435 * Clear: Perform initialization only if not actived
2436 */
2437 #define sa_RNG_CTRL_REINIT 0x0001
2438 /**
2439 * @def sa_RNG_CTRL_ENABLE_INT
2440 * Control Info -- Set: Interrupt mode
2441 * Clear: Poll mode
2442 */
2443 #define sa_RNG_CTRL_ENABLE_INT 0x0002
2444 /**
2445 * @def sa_RNG_CTRL_RESET
2446 * Control Info -- Set: RNG reset
2447 */
2448 #define sa_RNG_CTRL_RESET 0x0004
2449 /*@}*/
2450 /** @} */
2454 /**
2455 * @ingroup salld_api_structures
2456 * @brief SALLD RNG Configuration Structure
2457 *
2458 * Data structure defines the RNG configuration related parameters
2459 *
2460 */
2461 typedef struct {
2462 uint16_t ctrlBitfield; /**< Specify the initialization mode and other control information as defined
2463 at @ref SALLDRngConfigCtrlInfo */
2464 uint16_t clockDiv; /**< Specify the clock divider (1, 16) 0: default */
2465 uint32_t startupCycles; /**< Specify the number of clock cycles (2**8, 2**24) to start up
2466 the random number generator initially(0:default) */
2467 uint32_t minRefillCycles; /**< Specify the minimum number of clock cycles (2**6, 2**14) to generate
2468 the next random number (0:default) */
2469 uint32_t maxRefillCycles; /**< Specify the maximum number of clock cycles (2**8, 2**24) to generate
2470 the next random number (0:default) */
2471 } Sa_RngConfigParams_t;
2473 /**
2474 * @ingroup salld_api_structures
2475 * @brief SALLD RNG Output Structure
2476 *
2477 * This structure defines the random number output provided upon request
2478 * with @ref Sa_getRandomNum().
2479 */
2480 typedef struct {
2481 uint32_t hi; /**< Upper 32 bits of the 64-bit Random Number output */
2482 uint32_t lo; /**< Lower 32 bits of the 64-bit Random Number output */
2483 } Sa_RngData_t;
2485 /**
2486 * @ingroup salld_api_constants
2487 * @brief Define the maximum number of buffers the module (SALLD) can request
2488 *
2489 */
2490 #define sa_N_BUFS 1
2492 /**
2493 * @defgroup saBufIndex SA System Memory Buffer Index
2494 * @ingroup salld_api_constants
2495 * @{
2496 *
2497 * @name SA System Memory Buffer Index
2498 * @brief Define the buffer index of the SA system memory blocks.
2499 *
2500 */
2501 /* @{ */
2502 /**
2503 * @def sa_SYS_BUF_INST
2504 * SA LLD system instance buffer
2505 */
2506 #define sa_SYS_BUF_INST 0
2508 /* @} */
2509 /** @} */
2511 /** @name COMMON (Common Interface) APIs
2512 *
2513 */
2514 /*@{*/
2516 /**
2517 * @ingroup salld_api_functions
2518 * @brief Sa_getBufferReq returns the memory requirements for the SALLD instance.
2519 *
2520 * @details This function returns the memory buffer requirements in terms of the size and
2521 * alignment array. The SA LLD requires only one memory block as described below:
2522 * - SA Instance: SA instance data
2523 *
2524 * @param[in] sizeCfg Size configuration information
2525 * @param[out] sizes Array of size requirements
2526 * @param[out] aligns Array of alignment requirements
2527 * @retval Value @ref salldRetCodes
2528 *
2529 * @sa Sa_SizeCfg_t
2530 */
2531 int16_t Sa_getBufferReq (Sa_SizeCfg_t *sizeCfg, int sizes[], int aligns[]);
2533 /**
2534 * @ingroup salld_api_functions
2535 * @brief Sa_create creates the SA LLD instance. It initializes the SALLD instance
2536 * and its corresponding instance structure based on channel configuration data
2537 * such as the call-out table, and etc.
2538 *
2539 * @param[in] cfg Configuration information
2540 * @param[in] bases Array of the memory buffer base addresses
2541 * @param[out] pHandle Instance handle. This is a pointer to an initialized
2542 * instance structure.
2543 * @retval Value @ref salldRetCodes
2544 *
2545 * @sa Sa_Config_t
2546 *
2547 * @note The system buffers should be allocated from global accessible memory blocks and global
2548 * addresses should be used if the LLD instance is expected to be shared among multiple cores.
2549 *
2550 */
2551 int16_t Sa_create (Sa_Config_t *cfg, void* bases[], Sa_Handle *pHandle);
2553 /**
2554 * @ingroup salld_api_functions
2555 * @brief Sa_start activates the SA LLD instance
2556 *
2557 * @details This function activates the SA LLD instance. This function should
2558 * be called once at all other DSP cores which share the same SALLD
2559 * instance.
2560 *
2561 * @param[in] handle The PA LLD instance identifier
2562 * @param[in] cfg Configuration information
2563 * @retval Value @ref salldRetCodes
2564 *
2565 * @note: It is optional to call the function at the DSP core where Sa_create() is
2566 * invoked.
2567 */
2568 int16_t Sa_start (Sa_Handle handle, Sa_Config_t *cfg);
2570 /**
2571 * @ingroup salld_api_functions
2572 * @brief Sa_getShadowHandle queries the shadow system handle.
2573 *
2574 * @details This function returns the shadow system handle. The shadow system handle
2575 * is set to NULL if it does not exist. Refer to @ref appendix2 for details
2576 *
2577 * @param[in] handle The PA LLD instance identifier
2578 * @param[in] shandle Pointer to the shadow system handle
2579 * @retval Value @ref salldRetCodes
2580 *
2581 */
2582 int16_t Sa_getShadowHandle (Sa_Handle handle, Sa_Handle *shandle);
2585 /**
2586 * @ingroup salld_api_functions
2587 * @brief Sa_close deactivates the SA LLD instance
2588 *
2589 * @details This function deactivates the SA LLD instance, all the associated
2590 * memory buffers can be freed after this call.
2591 *
2592 * @param[in] handle The PA LLD instance identifier
2593 * @param[out] bases Array of the memory buffer base addresses
2594 * @retval Value @ref salldRetCodes
2595 */
2596 int16_t Sa_close (Sa_Handle handle, void* bases[]);
2598 /**
2599 * @ingroup salld_api_functions
2600 * @brief This function obtains SALLD system statistics.
2601 *
2602 * @param[in] handle SALLD instance identifier.
2603 * @param[in, out] stats pointer to system statistics
2604 * @retval Value @ref salldRetCodes
2605 */
2606 int16_t Sa_getSysStats (Sa_Handle handle, Sa_SysStats_t *stats);
2608 /**
2609 * @ingroup salld_api_functions
2610 * @brief This function controls the reset state of the SA Sub-System
2611 *
2612 * @details This function is used to assert or release reset for the sub-system. Asserting reset does not
2613 * reset any of the sub-system internal data, but only the packet processing modules. To acheive
2614 * a complete system reset the system-level reset must be asserted through the power controller.
2615 *
2616 * @param[in] handle SALLD instance identifier.
2617 * @param[in] newState Value @ref salldSubSysStates
2618 * @retval Value @ref salldSubSysStates
2619 * @pre None
2620 */
2621 Sa_State_t Sa_resetControl (Sa_Handle handle, Sa_State_t newState);
2623 /**
2624 * @ingroup salld_api_functions
2625 * @brief This function downloads a PDSP image to a PDSP core within the SA sub-system.
2626 *
2627 * @details This function is used to download an executable image to a packet processing module.
2628 *
2629 * @param[in] handle SALLD instance identifier.
2630 * @param[in] modId The PDSP number (0-1)
2631 * @param[in] image The image to download
2632 * @param[in] sizeBytes The size of the image
2633 * @retval Value @ref salldRetCodes
2634 * @pre The packet processing modules must be in reset. See @ref Sa_resetControl.
2635 */
2636 int16_t Sa_downloadImage (Sa_Handle handle, int modId, void* image, int sizeBytes);
2638 /**
2639 * @ingroup salld_api_functions
2640 * @brief The function is called to initialize and configure the RNG (Random Number Generator) module
2641 * inside SA
2642 *
2643 * @remark For a multi-core device, it is up to the upper-layer application to make sure that only
2644 * the master core performs the RNG hardware initialization.
2645 *
2646 * @param[in] handle SALLD instance identifier.
2647 * @param[in] cfg Pointer the RNG configuration parameters as defined at @ref Sa_RngConfigParams_t
2648 * @retval Value @ref salldRetCodes
2649 * @pre None
2650 */
2651 int16_t Sa_rngInit (Sa_Handle handle, Sa_RngConfigParams_t* cfg);
2653 /**
2654 * @ingroup salld_api_functions
2655 * @brief This function returns a 64-bit true random number
2656 *
2657 * @details This function is called to get a 64-bit true random number. It is a non-blocking function
2658 * call which indicates the random number is not available if the RNG is still in the
2659 * process of generating the next random number.
2660 * @remark For a multi-core device, it is up to the application to prevent this function from being invoked
2661 * by multiple CGEM cores simultaneously.
2662 *
2663 * @param[in] handle SALLD instance identifier.
2664 * @param[in] f_isr Flag to indicate whether it is called from interrupt srevice routine
2665 * @param[in] rnd Pointer to the 64-bit random number
2666 * @retval Value @ref salldRetCodes
2667 * @pre RNG is initialized
2668 */
2669 int16_t Sa_getRandomNum (Sa_Handle handle, uint16_t f_isr, Sa_RngData_t* rnd);
2671 /**
2672 * @ingroup salld_api_functions
2673 * @brief Sa_rngClose decativates the SA RNG module
2674 *
2675 * @details This function deactivates the SA RNG module and clears LLD internal state.
2676 *
2677 * @param[in] handle The PA LLD instance identifier
2678 * @retval Value @ref salldRetCodes
2679 */
2680 int16_t Sa_rngClose (Sa_Handle handle);
2682 /**
2683 * @ingroup salld_api_functions
2684 * @brief This function initializes the PKA (Public Key Accelerator) module inside SA
2685 *
2686 * @details The function is called to initialize the PKA module inside SA.
2687 * @remark For a multi-core device, it is up to the upper-layer application to make sure that only
2688 * the master core performs the PKA hardware initialization.
2689 *
2690 * @param[in] handle SALLD instance identifier.
2691 * @retval Value @ref salldRetCodes
2692 * @pre None
2693 */
2694 int16_t Sa_pkaInit (Sa_Handle handle);
2696 /**
2697 * @ingroup salld_api_functions
2698 * @brief This function triggers a large vector arithmetic operation through the PKA module
2699 *
2700 * @details The function is called to perform a large vector arithmetic operation through the PKA module.
2701 * It is considered as a blocking function call since it will wait for the PKA module to complete
2702 * the arithmetic operation. However, it only takes a few cycles for PKA to complete any operation.
2703 * This function also returns with error code immediately if the PKA is still in the process to
2704 * perform the previous operation or when timeout occurs.
2705 * @remark For a multi-core device, it is up to the application to prevent this function from being invoked
2706 * by multiple CGEM cores simultaneously.
2707 *
2708 * @param[in] handle SALLD instance identifier.
2709 * @param[in] pkaReqInfo Pointer to the PKA operation request information structure
2710 * @retval Value @ref salldRetCodes
2711 * @pre PKA is initialized
2712 */
2713 int16_t Sa_pkaOperation (Sa_Handle handle, Sa_PkaReqInfo_t* pkaReqInfo);
2715 /**
2716 * @ingroup salld_api_functions
2717 * @brief Sa_pkaClose decativates the SA PKA module
2718 *
2719 * @details This function deactivates the SA PKA module and clears LLD internal state.
2720 *
2721 * @param[in] handle The PA LLD instance identifier
2722 * @retval Value @ref salldRetCodes
2723 */
2724 int16_t Sa_pkaClose (Sa_Handle handle);
2726 /**
2727 * @ingroup salld_api_functions
2728 * @brief This function returns the SA system ID associated with the specified handle
2729 *
2730 * @details The function is called to request the SA system ID corresponding to the handle.
2731 *
2732 * @param[in] handle SALLD instance identifier.
2733 * @retval SA system ID
2734 * @pre Sa_create function should be called before calling this function
2735 */
2736 uint32_t Sa_getID (Sa_Handle handle);
2738 /**
2739 * @ingroup salld_api_functions
2740 * @brief Sa_getVersion returns the SA LLD version information
2741 *
2742 * @details This function is used to get the version information of the SA LLD in 0xAABBCCDD format.
2743 * where Arch (AA); API Changes (BB); Major (CC); Minor (DD)
2744 *
2745 * @retval 32-bit version information
2746 */
2747 uint32_t Sa_getVersion (void);
2750 /**
2751 * @ingroup salld_api_functions
2752 * @brief Sa_getVersionStr returns the SA LLD version string
2753 *
2754 * @details This function is used to get the version string of the SA LLD.
2755 *
2756 * @retval Version string
2757 */
2758 const char* Sa_getVersionStr (void);
2760 /**
2761 * @ingroup salld_api_functions
2762 * @brief Sa_getPDSPVersion returns the SA PDSP version information.
2763 *
2764 * @details This function is used to get the SA PDSP version information in 0xAABBCCDD format.
2765 * where Arch (AA); API Changes (BB); Major (CC); Minor (DD
2766 *
2767 * @param[in] handle SALLD instance identifier.
2768 * @param[in] modId The PDSP number (0-1)
2769 * @param[out] pVersion The pointer to PDSP version number
2770 * @retval Value @ref salldRetCodes
2771 * @pre The PDSP image should be downloaded successfully.
2772 *
2773 */
2774 int16_t Sa_getPDSPVersion (Sa_Handle handle, int modId, uint32_t *pVersion);
2776 /*@}*/ /* @name COMMON APIs */
2778 /**
2779 * @ingroup salld_api_constants
2780 * @brief Define the maximum number of buffers each SA LLD channel can request
2781 *
2782 */
2783 #define sa_CHAN_N_BUFS 1
2785 /**
2786 * @defgroup saChanBufIndex SA Channel Memory Buffer Index
2787 * @ingroup salld_api_constants
2788 * @{
2789 *
2790 * @name SA Channel Memory Buffer Index
2791 * @brief Define the buffer index of the SA channel memory blocks.
2792 *
2793 */
2794 /* @{ */
2795 /**
2796 * @def sa_CHAN_BUF_INST
2797 * SA LLD channel instance buffer
2798 */
2799 #define sa_CHAN_BUF_INST 0
2801 /* @} */
2802 /** @} */
2805 /** @name CHANNEL (Channel-Specific) APIs
2806 *
2807 */
2808 /*@{*/
2810 /**
2811 * @ingroup salld_api_functions
2812 * @brief Sa_chanGetBufferReq returns the memory requirements for an SALLD channel
2813 *
2814 * @details This function returns the memory buffer requirements in terms of the size and
2815 * alignment array. The SA Channel requires only one memory block as described below:
2816 * - SA Channel Instance: SA channel instance data
2817 *
2818 * @param[in] sizeCfg Size configuration information
2819 * @param[out] sizes Array of size requirements
2820 * @param[out] aligns Array of alignment requirements
2821 * @retval Value @ref salldRetCodes
2822 */
2823 int16_t Sa_chanGetBufferReq (Sa_ChanSizeCfg_t *sizeCfg, int sizes[], int aligns[]);
2825 /**
2826 * @ingroup salld_api_functions
2827 * @brief Sa_chanCreate creates the SALLD channel. It initializes an instance of SALLD
2828 * channel and its corresponding instance structure based on channel
2829 * configuration data such as the security protocol, and etc.
2830 *
2831 * @param[in] handle SALLD instance identifier.
2832 * @param[in] cfg Configuration information
2833 * @param[in] bases Array of the memory buffer base addresses
2834 * @param[out] pChanHdl Channel handle. This is a pointer to an initialized
2835 * instance structure.
2836 * @retval Value @ref salldRetCodes
2837 *
2838 * @note The channel buffers should be allocated from global accessible memory blocks and global
2839 * addresses should be used if this channel is expected to be shared among multiple cores.
2840 */
2841 int16_t Sa_chanCreate (Sa_Handle handle, Sa_ChanConfig_t *cfg, void* bases[],
2842 Sa_ChanHandle *pChanHdl);
2844 /**
2845 * @ingroup salld_api_functions
2846 * @brief Sa_chanClose decativates the SALLD channel. It clears the SALLD channel instance.
2847 * All the associated memory buffers can be freed after this call.
2848 *
2849 * @param[in] handle SALLD channel instance identifier
2850 * @param[out] bases Array of the memory buffer base addresses
2851 * @retval Value @ref salldRetCodes
2852 */
2853 int16_t Sa_chanClose (Sa_ChanHandle handle, void* bases[]);
2855 /**
2856 * @ingroup salld_api_functions
2857 * @brief This function controls the operations of a channel instance of SALLD. It is
2858 * used to configure and/or re-configure the SALLD channel with various control
2859 * information. This function should be called multiple times to configure and
2860 * activate the SALLD channel during the call setup period. Then it is typically
2861 * called to perform re-key operation subsequently.
2862 *
2863 * @param[in] handle SALLD channel instance identifier.
2864 * @param[in] chanCtrlInfo Pointer to SALLD channel control config structure.
2865 * @retval Value @ref salldRetCodes
2866 *
2867 * @sa Sa_ChanCtrlInfo_t
2868 */
2869 int16_t Sa_chanControl (Sa_ChanHandle handle, Sa_ChanCtrlInfo_t *chanCtrlInfo);
2871 /**
2872 * @ingroup salld_api_functions
2873 * @brief This function activates the local channel instance at other DSP cores. It should
2874 * be called once at any other DSP cores which invoke the same SALLD channel that
2875 * is created and configured at the master core. It is up to the master core
2876 * to make the channel handle public and accessible by other DSP cores after
2877 * channel creation and configuration.
2878 * The following APIs are supported at slave cores.
2879 * - Sa_chanReceiveData
2880 * - Sa_chanSendData
2881 * - Sa_chanGetStats
2882 * - Sa_chanGetID
2883 *
2884 * @param[in] handle SALLD channel instance identifier.
2885 * @retval Value @ref salldRetCodes
2886 *
2887 * @note: This function should be called prior to other channel APIs
2888 * such as Sa_chanSendData() and Sa_chanReceiveData() are invoked
2889 *
2890 */
2891 int16_t Sa_chanStart (Sa_ChanHandle handle);
2893 /**
2894 * @ingroup salld_api_functions
2895 * @brief Sa_chanGetShadowHandle queries the shadow channel handle.
2896 *
2897 * @details This function returns the shadow channel handle. The shadow channel handle
2898 * is set to NULL if it does not exist. Refer to @ref appendix2 for details
2899 *
2900 * @param[in] handle The PA LLD channel instance identifier
2901 * @param[in] shandle Pointer to the shadow channel handle
2902 * @retval Value @ref salldRetCodes
2903 *
2904 */
2905 int16_t Sa_chanGetShadowHandle (Sa_ChanHandle handle, Sa_ChanHandle *shandle);
2907 /**
2908 * @ingroup salld_api_functions
2909 * @brief This utility function processes packets received from the network. It performs IPSec ESP specific
2910 * post-SA operations on the decrypted and/or integrity-verified data packet. It also
2911 * performs the actual decryption/authentication operation in SW-only mode.
2912 *
2913 * @param[in] info ESP Tx/Rx information pointer.
2914 * @param[in] pktDesc Pointer to the packet descriptor structure.
2915 * @retval Value @ref salldRetCodes
2916 *
2917 * @sa Sa_PktDesc_t
2918 */
2919 int16_t salld_esp_post_proc_util (salldIpsecEspTxRxInfo_t *info, Sa_PktDesc_t* pktDesc);
2921 /**
2922 * @ingroup salld_api_functions
2923 * @brief This function processes packets received from the network. It performs protocol-specific
2924 * post-SA operations on the decrypted and/or integrity-verified data packet. It also
2925 * performs the actual decryption/authentication operation in SW-only mode.
2926 *
2927 * @param[in] handle SALLD channel instance identifier.
2928 * @param[in] pktInfo Pointer to the packet info structure.
2929 * @retval Value @ref salldRetCodes
2930 *
2931 * @sa Sa_PktInfo_t
2932 */
2933 int16_t Sa_chanReceiveData (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo);
2936 /**
2937 * @ingroup salld_api_functions
2938 * @brief This utility function processes the data packet to the networks. It performs IPSec ESP specific
2939 * operations to prepare the data packets to be encrypted and/or authenticated by the SA.
2940 * It also performs the actual encryption and/or authentication in the SW-only mode
2941 *
2942 * @param[in] info ESP Tx/Rx information pointer.
2943 * @param[in] pktDesc Pointer to the packet descriptor structure.
2944 * @retval Value @ref salldRetCodes
2945 *
2946 * @sa Sa_PktDesc_t
2947 *
2948 */
2949 int16_t salld_esp_pre_proc_util (salldIpsecEspTxRxInfo_t *info, Sa_PktDesc_t* pktDesc);
2951 /**
2952 * @ingroup salld_api_functions
2953 * @brief This function processes the data packet to the networks. It performs protocol-specific
2954 * operations to prepare the data packets to be encrypted and/or authenticated by the SA.
2955 * It also performs the actual encryption and/or authentication in the SW-only mode
2956 *
2957 * @param[in] handle SALLD channel instance identifier.
2958 * @param[in] pktInfo Pointer to the packet info structure.
2959 * @param[in] clear Flag indicating whether to force non-encryption
2960 * @retval Value @ref salldRetCodes
2961 *
2962 * @sa Sa_PktInfo_t
2963 *
2964 */
2965 int16_t Sa_chanSendData (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo, uint16_t clear);
2968 /**
2969 * @ingroup salld_api_functions
2970 * @brief This function obtains SALLD channel protocol-specific statistics.
2971 *
2972 * @param[in] handle SALLD channel instance identifier.
2973 * @param[in] flags Various control flags @ref SALLDStatsCtrlBit
2974 * @param[in, out] stats Pointer to protocol-specific statistics
2975 * @retval Value @ref salldRetCodes
2976 */
2977 int16_t Sa_chanGetStats (Sa_ChanHandle handle, uint16_t flags, Sa_Stats_t *stats);
2979 /**
2980 * @ingroup salld_api_functions
2981 * @brief Sa_chanGetID returns the SA channel ID associated with the specified handle
2982 *
2983 * @details The function is called to request the SA channel ID corresponding to the handle.
2984 *
2985 * @param[in] handle SALLD instance identifier.
2986 * @retval Channel ID
2987 * @pre Sa_chanInit function should be called before calling this function
2988 */
2989 uint32_t Sa_chanGetID (Sa_ChanHandle handle);
2991 /**
2992 * @ingroup salld_api_functions
2993 * @brief Sa_chanGetSwInfo returns the SA-specific software information required for all packets
2994 * to be delivered to SA.
2995 *
2996 * @details It is an optional utility function to query the SA-specific software information in
2997 * both directions in case Sa_chanSendData() is not used and/or the callout function
2998 * ChanRegister() is not implemented.
2999 *
3000 * In normal operation, the from-network SWInfo will be passed to module user via callout
3001 * function ChanRegister() and the to-network SWInfo will be passed to module user via API
3002 * Sa_chanSendData().
3003 *
3004 * @param[in] handle SALLD channel instance identifier.
3005 * @param[in] dir Packet direction as specified at @ref Sa_PktDir_t
3006 * @param[in] pChanSwInfo Pointer to SALLD software routing information structure.
3007 * @retval Value @ref salldRetCodes
3008 *
3009 * @sa Sa_SWInfo_t
3010 *
3011 */
3012 int16_t Sa_chanGetSwInfo (Sa_ChanHandle handle, uint16_t dir, Sa_SWInfo_t* pChanSwInfo);
3015 /*@}*/ /* @name Channel APIs */
3017 /** @name Utility APIs
3018 *
3019 */
3020 /*@{*/
3022 /**
3023 * @ingroup salld_api_functions
3024 * @brief This function verifies whether the security context buffer has been freed
3025 * by SA.
3026 *
3027 * @param[in] scBuf Pointer to the Security Context buffer.
3028 * @retval TRUE if buffer is free; FALSE if otherwise
3029 *
3030 */
3031 uint16_t Sa_isScBufFree (uint8_t* scBuf);
3033 /*@}*/ /* @name Utility APIs */
3035 /** @name SA LLD Macros
3036 *
3037 */
3038 /*@{*/
3040 /**
3041 * @ingroup salld_api_macros
3042 * @brief sa_MK_UINT32 is a simple utility macro which constructs a 32-bit word from 4 input bytes
3043 *
3044 * @param[in] a Input byte 1
3045 * @param[in] b Input byte 2
3046 * @param[in] c Input byte 3
3047 * @param[in] d Input byte 4
3048 *
3049 */
3050 #define sa_MK_UINT32(a, b, c, d) (((a) << 24) | ((b) << 16) | ((c) << 8) | (d))
3052 /**
3053 *
3054 * @ingroup salld_api_macros
3055 * @brief sa_mDmResetCmdLb: Reset the Command Label for Data Mode
3056 *
3057 * @details Inline macro API can be used to reset the Command Label
3058 * for Data Mode after first time initialization
3059 *
3060 * @param[in] updateInfo Command label updating control structure returned from SA LLD
3061 * @param[in] cmdLb Command Label Buffer
3062 *
3063 * @note: It is just a sample implemenation which should be optimized per use case
3064 */
3065 static inline
3066 void sa_mDmResetCmdLb(Sa_CmdLbUpdateInfo_t* updateInfo,
3067 uint32_t* cmdLb)
3068 {
3069 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_ENC)
3070 {
3071 /* Clear the encSize and encOffset field to simplify the operation in command label updating Macros */
3072 cmdLb[updateInfo->encSizeInfo.index] &= 0xffff0000UL;
3073 cmdLb[updateInfo->encOffsetInfo.index] &= 0x00ffffffUL;
3074 }
3076 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUTH)
3077 {
3078 /* Clear the authSize and authOffset field to simplify the operation in command label updating Macros */
3079 cmdLb[updateInfo->authSizeInfo.index] &= 0xffff0000UL;
3080 cmdLb[updateInfo->authOffsetInfo.index] &= 0x00ffffffUL;
3081 }
3083 if ( (updateInfo->subMode == sa_DM_CCM) ||
3084 (updateInfo->subMode == sa_DM_CCM_GEN) )
3085 {
3086 /* Clear AAD length field */
3087 cmdLb[2] &= 0xffff0000UL;
3089 }
3090 }
3092 /**
3093 *
3094 * @ingroup salld_api_macros
3095 * @brief salld_form_32bits_util: form 32 bits command label from a byte array
3096 *
3097 * @details Inline macro API can be used to generate the 32 bits word array from
3098 * byte array as b[0]<<24 | b[1]<<16 | b[2] << 8 | b[3].
3099 *
3100 * @param[in] cmdLb Command Label Buffer
3101 * @param[in] index start index of cmdLb
3102 * @param[in] offset start offset in the cmdLb 32-bit word
3103 * @param[in] bPtr byte array pointer
3104 * @param[in] bSize byte array size
3105 *
3106 */
3107 static inline
3108 void salld_form_32bits_util(uint32_t* cmdLb, uint8_t index, uint8_t offset, uint8_t* bPtr, uint8_t bSize)
3109 {
3110 uint32_t temp = 0;
3111 int bIndex = 0;
3112 int8_t iShift = 8 *( 3 - offset);
3113 int w32Size, bytesInlast32bWord;
3115 /* number of bytes to be formed in last 32-bit word */
3116 bytesInlast32bWord = (bSize + offset ) & 3;
3118 /* number of bytes to be formed into full 32-bit words */
3119 w32Size = bSize - offset - bytesInlast32bWord;
3121 /* Handle the un-aligned first 32 word that needs update specially */
3122 if (offset != 0)
3123 {
3124 while (iShift >= 0) {
3125 temp |= bPtr[bIndex ++] << iShift;
3126 iShift -= 8;
3127 }
3128 cmdLb[index ++] |= temp;
3129 }
3131 /* the loop runs for all full 32-bit words */
3132 while (bIndex < w32Size)
3133 {
3134 cmdLb[index ++] = bPtr[bIndex] << 24 | bPtr[bIndex+1] << 16 | \
3135 bPtr[bIndex + 2] << 8 | bPtr[bIndex + 3];
3136 bIndex += 4;
3137 }
3139 /* Handle any un-handled (remaining) bytes towards the end */
3140 if (bytesInlast32bWord)
3141 {
3142 iShift = 24;
3143 temp = 0;
3144 while (bytesInlast32bWord) {
3145 temp |= bPtr[bIndex ++] << iShift;
3146 iShift -= 8;
3147 bytesInlast32bWord --;
3148 }
3149 cmdLb[index] = temp;
3150 }
3151 }
3153 /**
3154 *
3155 * @ingroup salld_api_macros
3156 * @brief sa_mDmUpdateCmdLb_ccm_gen: Update the command label for Data Mode in CCM general case
3157 *
3158 * @details Inline macro API can be used to update the command label per packet
3159 * for Data Mode during Encryption/Decryption request to SA.
3160 *
3161 * @param[in] encOffset Offset to the encrypted/decrypted data in the
3162 * packet in bytes
3163 * @param[in] encSize Number of bytes to be encrypted or decrypted
3164 * @param[in] pEncIV Initialization vectors if applicable for
3165 * encryption mode.
3166 * @param[in] aadSize Number of additional data to be authenticated in bytes
3167 * @param[in] aad Pointer to the additional authenticated data
3168 * @param[in] pCmdlUpdate Command label updating control structure returned from SA LLD
3169 * @param[in] cmdLb Command Label Buffer
3170 *
3171 * @note: It is just a sample implemenation for generic CCM use cases
3172 *
3173 */
3174 static inline
3175 void sa_mDmUpdateCmdLb_ccm_gen(uint8_t encOffset,
3176 uint16_t encSize,
3177 uint8_t* pEncIV,
3178 uint8_t aadSize,
3179 uint8_t* aad,
3180 Sa_CmdLbUpdateInfo_t* pCmdlUpdate,
3181 uint32_t* cmdLb)
3182 {
3183 uint8_t *iv = pEncIV;
3185 /* Handle Option 1, (Option 2 & Option 3) in two different groups */
3186 /* Update the command label header (8 byte) */
3187 cmdLb[0] |= encSize;
3188 cmdLb[1] |= ((uint32_t)encOffset << 24);
3190 /* Option 1 Update: if AAD size is 0, no updates to Option 1 */
3191 if ( (aadSize > 0) &&
3192 (aadSize <= 14) )
3193 {
3194 /* Option 1: B1 (aadlen | AAD ) (16 byte) */
3195 /* update AAD */
3196 salld_form_32bits_util(&cmdLb[0], pCmdlUpdate->aadInfo.index, \
3197 pCmdlUpdate->aadInfo.offset, &aad[0], aadSize);
3198 }
3200 /* Option 2 update IV: B0 (flag | salt | IV | encypted data len) (16 byte) */
3201 salld_form_32bits_util(&cmdLb[0], pCmdlUpdate->encIvInfo.index, \
3202 pCmdlUpdate->encIvInfo.offset, iv, pCmdlUpdate->encIvInfo.size);
3204 cmdLb[9] &= 0xFFFF0000UL; /* Clear the lower 16 bits */
3205 cmdLb[9] |= encSize; /* Set with encoder size */
3207 /* Option 3: AES-CTR IV (salt| IV | 0) (16 byte) */
3208 /* Insert IV and encrypted data len */
3209 /* IV1 & 2*/
3210 cmdLb[10] = cmdLb[6] & 0x07FFFFFFUL;
3211 cmdLb[11] = cmdLb[7];
3212 cmdLb[12] = cmdLb[8];
3213 cmdLb[13] = cmdLb[9] & 0xFFFF0000UL;
3214 }
3216 /**
3217 *
3218 * @ingroup salld_api_macros
3219 * @brief sa_mDmUpdateCmdLb_ccm_wimax: Update the command label for CCM-WiMax
3220 *
3221 * @details Inline macro API can be used to update the command label per packet
3222 * for Data Mode during Encryption/Decryption request to SA.
3223 *
3224 * @param[in] encOffset Offset to the encrypted/decrypted data in the
3225 * packet in bytes
3226 * @param[in] encSize Number of bytes to be encrypted or decrypted
3227 * @param[in] gmh generic mac header pointer.
3228 * @param[in] sn sequence number pointer
3229 * @param[in] cmdLb Command Label Buffer
3230 *
3231 * @note: It is just a sample implemenation for CCM-WiMax (optimal implementation)
3232 *
3233 */
3234 static inline
3235 void sa_mDmUpdateCmdLb_ccm_wimax (
3236 uint8_t encOffset,
3237 uint16_t encSize,
3238 uint8_t* gmh, /* 5 bytes (excluding HCS (header check sequence) */
3239 uint8_t* sn, /* 4 bytes of sequence number */
3240 uint32_t* cmdLb)
3241 {
3244 cmdLb[0] |= encSize;
3245 cmdLb[1] |= ((uint32_t)encOffset << 24);
3247 /* AAD (none) */
3249 /* Option 2: B0 (flag | nonce | encypted data len) (16 byte) */
3250 /* Insert IV and encrypted data len */
3251 cmdLb[6] |= ((gmh[0] << 16) | \
3252 (gmh[1] << 8) | \
3253 (gmh[2]) );
3254 cmdLb[7] = ((gmh[3] << 24) | (gmh[4] << 16));
3255 cmdLb[8] = ((sn[0] << 8) | (sn[1]));
3256 cmdLb[9] = ((sn[2] << 24) | (sn[3] << 16) | encSize);
3258 /* Option 3: AES-CTR IV (flag | nonce | 0) (16 byte) */
3259 cmdLb[10] = cmdLb[6] & 0x07FFFFFFUL;
3260 cmdLb[11] = cmdLb[7];
3261 cmdLb[12] = cmdLb[8];
3262 cmdLb[13] = cmdLb[9] & 0xFFFF0000UL;
3263 }
3265 /**
3266 *
3267 * @ingroup salld_api_macros
3268 * @brief sa_mDmUpdateCmdLb: Update the command label for Data Mode for IPSEC,SRTP
3269 *
3270 * @details Inline macro API can be used to update the command label per packet
3271 * for Data Mode during Encryption/Decryption request to SA.
3272 *
3273 * @param[in] encOffset Offset to the encrypted/decrypted data in the
3274 * packet in bytes
3275 * @param[in] encSize Number of bytes to be encrypted or decrypted
3276 * @param[in] pEncIV Initialization vectors if applicable for
3277 * encryption mode.
3278 * @param[in] authOffset Offset to the (To be) authenticated data in the
3279 * packet in bytes
3280 * @param[in] authSize Number of bytes to be authenticated
3281 * @param[in] pAuthIV Initialization vectors if applicable for
3282 * authentication modes.
3283 * @param[in] aadSize Number of additional data to be authenticated in bytes
3284 * @param[in] aad Pointer to the additional authenticated data
3285 * @param[in] pDataBuf Pointer to data buffer
3286 * @param[in] updateInfo Command label updating control structure returned from SA LLD
3287 * @param[in] cmdLb Command Label Buffer
3288 *
3289 * @note: It is just a sample implemenation for below use cases:
3290 * IPSEC
3291 * SRTP
3292 *
3293 */
3294 static inline
3295 void sa_mDmUpdateCmdLb(uint8_t encOffset,
3296 uint16_t encSize,
3297 uint8_t* pEncIV,
3298 uint8_t authOffset,
3299 uint16_t authSize,
3300 uint8_t* pAuthIV,
3301 uint8_t aadSize,
3302 uint8_t* aad,
3303 uint8_t* pDataBuf,
3304 Sa_CmdLbUpdateInfo_t* updateInfo,
3305 uint32_t* cmdLb)
3306 {
3308 switch (updateInfo->subMode)
3309 {
3310 case sa_DM_GEN: /* General Mode operation */
3311 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_ENC)
3312 {
3313 cmdLb[updateInfo->encSizeInfo.index] |= encSize;
3314 cmdLb[updateInfo->encOffsetInfo.index] |= ((uint32_t)encOffset << 24);
3316 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_ENC_IV)
3317 {
3318 uint32_t *data = &cmdLb[updateInfo->encIvInfo.index];
3319 uint8_t *iv = pEncIV;
3321 data[0] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
3322 data[1] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
3324 if (updateInfo->encIvInfo.size > 8)
3325 {
3326 data[2] = sa_MK_UINT32(iv[8], iv[9], iv[10], iv[11]);
3327 data[3] = sa_MK_UINT32(iv[12], iv[13], iv[14], iv[15]);
3328 }
3329 }
3330 }
3332 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUTH)
3333 {
3334 cmdLb[updateInfo->authSizeInfo.index] |= authSize;
3335 cmdLb[updateInfo->authOffsetInfo.index] |= (authOffset << 24);
3337 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUTH_IV)
3338 {
3339 uint32_t *data = &cmdLb[updateInfo->authIvInfo.index];
3340 uint8_t *iv = pAuthIV;
3342 data[0] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
3343 data[1] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
3345 if (updateInfo->authIvInfo.size > 8)
3346 {
3347 data[2] = sa_MK_UINT32(iv[8], iv[9], iv[10], iv[11]);
3348 data[3] = sa_MK_UINT32(iv[12], iv[13], iv[14], iv[15]);
3349 }
3350 }
3352 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUX_KEY)
3353 {
3355 int offset = (authSize & 0xF)?4:0;
3356 memcpy(&cmdLb[updateInfo->auxKeyInfo.index], &updateInfo->auxKey[offset], 16);
3357 }
3358 }
3359 break;
3362 case sa_DM_CCM:
3363 {
3364 uint8_t *iv = pEncIV;
3366 cmdLb[0] |= encSize;
3367 cmdLb[1] |= ((uint32_t)encOffset << 24);
3369 /* AAD */
3370 cmdLb[2] |= ((aad[0] << 8) + aad[1]);
3371 cmdLb[3] = sa_MK_UINT32(aad[2], aad[3], aad[4], aad[5]);
3372 if (aadSize == 8)
3373 {
3374 cmdLb[4] = (aad[6] << 24) + (aad[7] << 16);
3375 }
3376 else
3377 {
3378 cmdLb[4] = sa_MK_UINT32(aad[6], aad[7], aad[8], aad[9]);
3379 cmdLb[5] = (aad[10] << 24) + (aad[11] << 16);
3380 }
3382 /* IV1 & 2*/
3383 cmdLb[11] = cmdLb[7] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
3384 cmdLb[12] = cmdLb[8] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
3386 /* data length 2 */
3387 cmdLb[9] = encSize;
3389 }
3390 break;
3392 case sa_DM_GCM:
3393 {
3395 uint8_t *iv = pEncIV;
3397 cmdLb[0] |= encSize;
3398 cmdLb[1] |= ((uint32_t)encOffset << 24);
3400 /* AAD */
3401 cmdLb[4] = sa_MK_UINT32(aad[0], aad[1], aad[2], aad[3]);
3402 cmdLb[5] = sa_MK_UINT32(aad[4], aad[5], aad[6], aad[7]);
3403 if (aadSize == 12)
3404 {
3405 cmdLb[6] = sa_MK_UINT32(aad[8], aad[9], aad[10], aad[11]);
3406 }
3408 /* IV */
3409 cmdLb[9] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
3410 cmdLb[10] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
3412 /* data length 2 */
3413 cmdLb[3] = encSize << 3;
3415 }
3416 break;
3418 case sa_DM_GMAC:
3419 {
3420 uint8_t *iv = pAuthIV;
3421 uint8_t *payload = pDataBuf + authOffset;
3422 uint8_t dataAppended = 16 - aadSize; /* payload appended to AAD in bytes */
3424 cmdLb[0] |= authSize - dataAppended;
3425 cmdLb[1] |= ((authOffset + dataAppended) << 24);
3427 /* AAD */
3428 cmdLb[4] = sa_MK_UINT32(aad[0], aad[1], aad[2], aad[3]);
3429 cmdLb[5] = sa_MK_UINT32(aad[4], aad[5], aad[6], aad[7]);
3430 if (aadSize == 8)
3431 {
3432 cmdLb[6] = sa_MK_UINT32(payload[0], payload[1], payload[2], payload[3]);
3433 cmdLb[7] = sa_MK_UINT32(payload[4], payload[5], payload[6], payload[7]);
3434 }
3435 else
3436 {
3437 cmdLb[6] = sa_MK_UINT32(aad[8], aad[9], aad[10], aad[11]);
3438 cmdLb[7] = sa_MK_UINT32(payload[0], payload[1], payload[2], payload[3]);
3439 }
3441 /* IV */
3442 cmdLb[9] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
3443 cmdLb[10] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
3445 /* data length 2 */
3446 cmdLb[3] = (authSize + aadSize) << 3;
3448 }
3449 break;
3451 case sa_DM_GMAC_AH:
3452 {
3453 uint8_t *iv = pAuthIV;
3455 cmdLb[0] |= authSize;
3456 cmdLb[1] |= (authOffset << 24);
3458 /* data length 2 */
3459 cmdLb[3] = (authSize) << 3;
3461 /* IV */
3462 cmdLb[5] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
3463 cmdLb[6] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
3465 }
3466 break;
3469 default:
3470 /* Error handling */
3471 break;
3472 }
3473 }
3475 /**
3476 * @ingroup salld_api_structures
3477 * @brief Sa_psInfo_t defines the PS Info data used by SASS
3478 *
3479 * @details Sa_psInfo_t defines the Protocol-specific information required by SASS
3480 * - word[0] contains command, payload offset and payload length described below:
3481 * -SRTP/AC: offset to the RTP header; RTP payload length including ICV
3482 * -IPSEC AH: offset to the Outer IP; IP payload length
3483 * -IPSEC ESP: offset to the ESP header; ESP papload length including ICV
3484 * - word[1] contains 32-bit count-C for certain 3GPP ciphering and encryption modes
3485 * - word[2:5] contain up to 16-byte IV in array of 32-bit words for certain 3GPP
3486 * ciphering and encryption modes
3487 * @note: Use PS Info constructing Macros to format the PS Info data
3488 */
3490 typedef struct {
3491 uint32_t word[6]; /**< PS Info control block word 0-5 */
3492 } Sa_psInfo_t;
3494 /**
3495 * @ingroup salld_api_macros
3496 * @{
3497 * @name SA PS Info Constructing Macros
3498 * Macros used by the SA PS Info Command
3499 *
3500 */
3501 /*@{*/
3502 #define sa_PSINFO_FORMAT_CMD(x, offset, len) ((x)->word[0] = (0x20000000UL | ((offset) << 16) | (len))) /**< Format the PS Info header */
3503 #define sa_PSINFO_SET_COUNTC(x, countC) ((x)->word[1] = (countC)) /**< Constructing Count-C */
3504 static inline void sa_PSINFO_SET_IV(Sa_psInfo_t *x, uint32_t *iv, int ivSize) /**< Constructing IV */
3505 {
3506 int i;
3507 x->word[0] |= ((ivSize + 8) << 24);
3508 for( i = 0; i < ivSize/4 ; i++)
3509 x->word[i+ 2] = iv[i];
3510 }
3511 /*@}*/
3512 /** @} */
3514 /* @} */ /* ingroup */
3516 /*@}*/ /* @name SA LLD Macros */
3519 /**
3520 * @page appendix1 3GPP Opeartion and PDU formats
3521 *
3522 * There are many variation of PDU formats specified by the various 3GPP Protocols.
3523 * All supported 3GPP operations and data formats are described below:
3524 *
3525 * @par GSM:
3526 * Supported PDU types:
3527 *
3528 * @verbatim
3531 0 1 2 3 4 5 6 7
3532 +-+-+-+-+-+-+-+-+
3533 | |
3534 + IV (8/16byte) |
3535 | |
3536 +>+-+-+-+-+-+-+-+-+
3537 | | |
3538 | | |
3539 | | Data |
3540 | | |
3541 | | |
3542 | +-+-+-+-+-+-+-+-+
3543 |
3544 |-> Ciphering Unit
3546 Figure 1. Ciphering Unit of a GSM PDU.
3547 @endverbatim
3548 *
3549 * @par
3550 * Ciphering algorithm: GSM A5/3, ECSD A5/3, GAE3, Kasumi-F8
3551 * @par
3552 * Key Stream Generation:
3553 * - Input to SA: 64-bit IV plus all zero payload
3554 * - Output from SA: 64-bit IV plus key stream (228 bit for GSM A5/3, 696 bit for ECSD A5/3, varialbe length for GAE3)
3555 * @par
3556 * Full Encryption/Decryption:
3557 * - Input to SA: 64/128-bit IV plus payload
3558 * - Output from SA: 64/128-bit IV plus encryped/decrypted paylaod
3559 *
3560 * @par WCDMA:
3561 * Supported PDU types:
3562 *
3563 * @verbatim
3566 0 1 2 3 4 5 6 7
3567 +-+-+-+-+-+-+-+-+
3568 |DC| Seq Num |
3569 +-+-+-+-+-+-+-+-+
3570 |Seq Num |P| HE|
3571 +>+-+-+-+-+-+-+-+-+
3572 | | Length Ind. |E|
3573 | +-+-+-+-+-+-+-+-+
3574 | | |
3575 | | |
3576 | | Data |
3577 | | |
3578 | | |
3579 | +-+-+-+-+-+-+-+-+
3580 | | PAD or piggy-backed STATUS PDU
3581 | +-+-+-+-+-+-+-+-+
3582 |
3583 |-> Ciphering Unit
3586 Figure 2. Ciphering Unit of a WCDMA AMD PDU.
3589 0 1 2 3 4 5 6 7
3590 +-+-+-+-+-+-+-+-+
3591 | Seq Num |E|
3592 +>+-+-+-+-+-+-+-+-+
3593 | | Length Ind. |E|
3594 | +-+-+-+-+-+-+-+-+
3595 | | |
3596 | | |
3597 | | Data |
3598 | | |
3599 | | |
3600 | +-+-+-+-+-+-+-+-+
3601 |
3602 |-> Ciphering Unit
3605 Figure 3. Ciphering Unit of a WCDMA UMD PDU.
3608 0 1 2 3 4 5 6 7
3609 +-+-+-+-+-+-+-+-+
3610 | |
3611 | Count-C |
3612 | (4-byte) |
3613 | |
3614 +>+-+-+-+-+-+-+-+-+
3615 | | |
3616 | | |
3617 | | Data |
3618 | | |
3619 | | |
3620 | +-+-+-+-+-+-+-+-+
3621 |
3622 |-> Ciphering Unit
3624 Figure 4. Ciphering Unit of a WCDMA TMD PDU.
3625 @endverbatim
3627 *
3628 * @par
3629 * Ciphering algorithm: Kasumi/F8,Snow 3G/F8, AES-CTR
3630 *
3631 * @par
3632 * From Air Traffic (Decryption) :
3633 * - Input to SA:
3634 * - PDU header plus payload for RLC AMD/UMD PDU
3635 * - Payload with 32-bit Count-C in the CPPI header for TMD MAC PDU
3636 * - Output from SA:
3637 * - PDU header plus decrypted payload for RLC AMD/UMD PDU
3638 * - Decrypted payload for TMD MAC PDU
3639 *
3640 * @par
3641 * To Air Traffic (Encryption) :
3642 * - Input to SA:
3643 * - PDU header plus payload for RLC AMD/UMD PDU
3644 * - Payload for TMD MAC PDU
3645 * - Output from SA:
3646 * - PDU header plus encrypted payload for RLC AMD/UMD PDU
3647 * - 32-bit Count-C plus encrypted payload for TMD MAC PDU
3648 *
3649 *
3650 * @par LTE:
3651 * Supported PDU types:
3652 *
3653 * @verbatim
3655 0 1 2 3 4 5 6 7
3656 +-+-+-+-+-+-+-+-+
3657 | |
3658 | Count-C |
3659 | (4-byte) |
3660 | |
3661 +>+-+-+-+-+-+-+-+-+
3662 | | |
3663 | | |
3664 | | Data |
3665 | | |
3666 | | |
3667 | +-+-+-+-+-+-+-+-+
3668 |
3669 |-> Ciphering Unit
3671 Figure 5. Ciphering Unit of a PDCP Data PDU.
3674 0 1 2 3 4 5 6 7
3675 +-+-+-+-+-+-+-+-+ <+
3676 |R R R| PDCP SN | |
3677 +>+-+-+-+-+-+-+-+-+ |
3678 | | | |
3679 | | | |
3680 | | Data | |
3681 | | | |
3682 | | | |
3683 | +-+-+-+-+-+-+-+-+ |-> Authentication Unit
3684 | | MAC-I |
3685 | | (4 byte) |
3686 | +-+-+-+-+-+-+-+-+
3687 |
3688 |-> Ciphering Unit
3690 Figure 6. PDCP Control Plane Data Uint for SRBs
3691 @endverbatim
3692 *
3693 * @par
3694 * Ciphering algorithm: Snow 3G/F8, AES-CTR
3695 * Authentication algorithm: CMAC
3696 *
3697 * @par
3698 * From Air Traffic (Decryption and/or Authentication verification) :
3699 * - Input to SA:
3700 * - PDCP Data with 32-bit Count-C in the CPPI header for the Data Plane PDU
3701 * - PDCP Header plus Data and MAC-I with 32-bit Count-C in the CPPI header for the Control Plane PDU
3702 * - Output from SA: 32-bit Count-C plus decrypted PDCP PDU Data
3703 * - PDCP Data for the Data Plane PDU
3704 * - PDCP Header plus Data and MAC-I for the Control Plane PDU
3705 *
3706 * @par
3707 * To Air Traffic (Encryption and/or Authentication) :
3708 * - Input to SA:
3709 * - PDCP Data for the Data Plane PDU
3710 * - PDCP Header plus Data and MAC-I with 32-bit Count-C in the CPPI header for the Control Plane PDU
3711 * - Output from SA: 32-bit Count-C plus encrypted PDCP PDU Data
3712 * - 32-bit Count-C plus PDCP Data for the Data Plane PDU
3713 * - PDCP Header plus Data and MAC-I for the Control Plane PDU
3714 */
3716 /**
3717 * @page appendix2 Shadow Instance for mixed-Endian operation
3718 *
3719 * The SASS supports mixed-endianess operating mode such that the channel is created and configured by the master
3720 * processor, (e.g. ARM which is outside of SoC), while the data processing is handled by slave processor(s)
3721 * (e.g. DSPs). When in this mode, SA LLD must create and maintain a shadow instance, which is a copy of
3722 * the master instance with opposite endianess. New APIs are created to query the shadow instances, which should be
3723 * passed to and used by the slave processor(s).
3724 *
3725 * @note: Only the following use case is supported at this moment, further enhancements may be provided:
3726 * - IPSEC ESP/AH mode
3727 * - Control Path at ARM and Data Path at DSPs
3728 *
3729 */
3732 #ifdef __cplusplus
3733 }
3734 #endif
3736 #endif /* _SALLD_H */
3738 /* nothing past this point */