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-2018
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 /*
94 * Shut off: remark #880-D: parameter "descType" was never referenced
95 *
96 * This is better than removing the argument since removal would break
97 * backwards compatibility
98 */
99 #ifdef _TMS320C6X
100 #pragma diag_suppress 880
101 #pragma diag_suppress 681
102 #elif defined(__GNUC__)
103 /* Same for GCC:
104 * warning: unused parameter descType [-Wunused-parameter]
105 * expectation is all these catch up with some other intelligent
106 * tools like coverity, Klocwork etc, instead of dump GNU
107 * warnings
108 */
109 #pragma GCC diagnostic push
110 #pragma GCC diagnostic ignored "-Wunused-parameter"
111 #pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
112 #endif
115 /* Define SALLD Module as a master group in Doxygen format and add all SA LLD API
116 definitions to this group. */
117 /** @defgroup salld_module SA LLD Module API
118 * @{
119 */
120 /** @} */
122 /** @defgroup salld_api_functions SA LLD Functions
123 * @ingroup salld_module
124 */
126 /** @defgroup salld_api_macros SA LLD Macros
127 * @ingroup salld_module
128 */
130 /** @defgroup salld_api_structures SA LLD Data Structures
131 * @ingroup salld_module
132 */
134 /** @defgroup salld_api_constants SA LLD Constants (enums and defines)
135 * @ingroup salld_module
136 */
139 /**
140 * @defgroup salldDebugMessageTypes SALLD Debug message types
141 * @ingroup salld_api_constants
142 * @{
143 *
144 * @name SALLD Debug message types
145 *
146 * Debug message types used by debugInfo().
147 */
148 /*@{*/
149 /**
150 * @def sa_DBG_INFORMATIONAL
151 * SALLD Debug Message Type -- SA LLD general debug information message.
152 */
153 #define sa_DBG_INFORMATIONAL 0
154 /**
155 * @def sa_DBG_WARNING
156 * SALLD Debug Message Type -- SA LLD warning debug information message.
157 */
158 #define sa_DBG_WARNING 1
160 /**
161 * @def sa_DBG_FATAL_ERROR
162 * SALLD Debug Message Type -- SA LLD critical debug information message.
163 */
164 #define sa_DBG_FATAL_ERROR 2
165 /*@}*/
166 /** @} */
168 /**
169 * @defgroup salldDebugMessageCodes SALLD Debug message codes
170 * @ingroup salld_api_constants
171 * @{
172 *
173 * @name SALLD Debug message codes
174 *
175 * Debug message codes used by debugInfo().
176 */
177 /*@{*/
178 /**
179 * @def sa_MSG_NO_MKI_LEN_CHANGE_ON_FLY
180 * SALLD Debug Message Code -- One-the-fly MKI change is not supported.
181 */
182 #define sa_MSG_NO_MKI_LEN_CHANGE_ON_FLY 1
183 /**
184 * @def sa_MSG_MKI_LEN_IS_ZERO
185 * SALLD Debug Message Code -- MKI length is zero.
186 */
187 #define sa_MSG_MKI_LEN_IS_ZERO 2
188 /*@}*/
189 /** @} */
191 /**
192 * @defgroup salldSubSysStates SALLD Sub-System Queries and States
193 * @ingroup salld_api_constants
194 * @{
195 *
196 * @name SALLD Sub-System Queries and States
197 *
198 * SA Sub-System reset state and query arguments used by API function @ref Sa_resetControl
199 */
200 /*@{*/
201 /**
202 * @def sa_STATE_RESET
203 * The Sub-System is in reset.
204 */
205 #define sa_STATE_RESET 0 /**< Sub-System state reset */
207 /**
208 * @def sa_STATE_ENABLE
209 * The Sub-System state is enabled.
210 */
211 #define sa_STATE_ENABLE 1 /**< Sub-System state enable */
213 /**
214 * @def sa_STATE_QUERY
215 * Query the Sub-System state.
216 */
217 #define sa_STATE_QUERY 2 /**< Query the Sub-System state */
219 /**
220 * @def sa_STATE_INCONSISTENT
221 * The Sub-System state is partially enabled.
222 */
223 #define sa_STATE_INCONSISTENT 3 /**< Sub-System is partially enabled */
225 /**
226 * @def sa_STATE_INVALID_REQUEST
227 * Invalid state command to the Sub-System.
228 */
229 #define sa_STATE_INVALID_REQUEST 4 /**< Invalid state command to the Sub-System */
231 /**
232 * @def sa_STATE_ENABLE_FAILED
233 * The Sub-System do not respond after restart.
234 */
235 #define sa_STATE_ENABLE_FAILED 5 /**< The Sub-System did not respond after restart */
236 /**
237 * @def sa_STATE_INVALID
238 * The Sub-System is at an invalid state for requested operation.
239 */
240 #define sa_STATE_INVALID 6 /**< The Sub-System at an invalid state for requested operation */
242 /*@}*/
243 /** @} */
245 /**
246 * @ingroup salld_api_structures
247 * @brief Sa_State_t defines the operating state of the security accelerator sub-system
248 *
249 * @details The values in @ref salldSubSysStates are used both to set the state of the security accelerator
250 * sub-system (sa_STATE_RESET and sa_STATE_ENABLE) as well as show the current state
251 * of the system (all values).
252 */
253 typedef int Sa_State_t;
255 /**
256 * @defgroup salldRetCodes SALLD Function Return Codes
257 * @ingroup salld_api_constants
258 * @{
259 *
260 * @name SALLD Function Return Codes
261 *
262 * Error codes returned by SALLD API functions.
263 */
264 /*@{*/
265 /**
266 * @def sa_ERR_OK
267 * SALLD Return Codes -- No Error.
268 */
269 #define sa_ERR_OK 0
270 /**
271 * @def sa_ERR_GEN
272 * SALLD Return Codes -- General Error.
273 */
274 #define sa_ERR_GEN -1
275 /**
276 * @def sa_ERR_PARAMS
277 * SALLD Return Codes -- Incorrect Input parameters.
278 */
279 #define sa_ERR_PARAMS -2
280 /**
281 * @def sa_ERR_NOMEM
282 * SALLD Return Codes -- Memory buffers not avialable.
283 */
284 #define sa_ERR_NOMEM -3
286 /**
287 * @def sa_ERR_INV_BUF (deprecated)
288 * SALLD Return Codes -- Invalid buffers.
289 */
290 #define sa_ERR_INV_BUF -4
291 /**
292 * @def sa_ERR_INV_PROTO_TYPE
293 * SALLD Return Codes -- Unsupported security protocol type.
294 */
295 #define sa_ERR_INV_PROTO_TYPE -5
296 /**
297 * @def sa_ERR_NO_CTX_BUF
298 * SALLD Return Codes -- Required Context Buffer not available.
299 */
300 #define sa_ERR_NO_CTX_BUF -6
301 /**
302 * @def sa_ERR_KEY_EXPIRED
303 * SALLD Return Codes -- Security Key is expired.
304 */
305 #define sa_ERR_KEY_EXPIRED -7
306 /**
307 * @def sa_ERR_REPLAY_OLD
308 * SALLD Return Codes -- Receive Packet is out of replay window range.
309 */
310 #define sa_ERR_REPLAY_OLD -8
311 /**
312 * @def sa_ERR_REPLAY_DUP
313 * SALLD Return Codes -- Duplicated Packet is received.
314 */
315 #define sa_ERR_REPLAY_DUP -9
316 /**
317 * @def sa_ERR_AUTH_FAIL
318 * SALLD Return Codes -- Authentication Failure.
319 */
320 #define sa_ERR_AUTH_FAIL -10
321 /**
322 * @def sa_ERR_PADDING_FAIL
323 * SALLD Return Codes -- ESP Padding Verification Failure.
324 */
325 #define sa_ERR_PADDING_FAIL -11
326 /**
327 * @def sa_ERR_CLOSE_PENDING
328 * SALLD Return Codes -- Close still pending, wait for Security context to be freed.
329 */
330 #define sa_ERR_CLOSE_PENDING -12
331 /**
332 * @def sa_ERR_UNSUPPORTED
333 * SALLD Return Codes -- API is not supported.
334 */
335 #define sa_ERR_UNSUPPORTED -13
336 /**
337 * @def sa_ERR_STATS_UNAVAIL
338 * SALLD Return Codes -- Statistics is not available yet.
339 */
340 #define sa_ERR_STATS_UNAVAIL -14
341 /**
342 * @def sa_ERR_MODULE_BUSY
343 * SALLD Return Codes -- Module (RNG or PKA) is busy serving pending request.
344 */
345 #define sa_ERR_MODULE_BUSY -15
346 /**
347 * @def sa_ERR_MODULE_UNAVAIL
348 * SALLD Return Codes -- Module (RNG or PKA) is not available (initialized) yet.
349 */
350 #define sa_ERR_MODULE_UNAVAIL -16
351 /**
352 * @def sa_ERR_PKA_TIMEOUT
353 * SALLD Return Codes -- PKA operation timeout.
354 */
355 #define sa_ERR_PKA_TIMEOUT -17
356 /**
357 * @def sa_ERR_SWINFO_UNAVAIL
358 * SALLD Return Codes -- Software Information is not available yet.
359 */
360 #define sa_ERR_SWINFO_UNAVAIL -18
361 /**
362 * @def sa_ERR_INV_HANDLE
363 * SALLD Return Codes -- Invalid system or channel handles.
364 */
365 #define sa_ERR_INV_HANDLE -19
366 /**
367 * @def sa_ERR_INV_ENDIAN_MODE
368 * SALLD Return Codes -- System or Channel instance using the different endian mode than the processor.
369 */
370 #define sa_ERR_INV_ENDIAN_MODE -20
371 /**
372 * @def sa_ERR_SCRATCH_MEMORY_FULL
373 * SALLD Return Codes -- No avail scratch memory for key storage
374 */
375 #define sa_ERR_SCRATCH_MEMORY_FULL -21
376 /**
377 * @def sa_ERR_PACKET
378 * SALLD Return Codes -- Error in the input packet such that SALLD is not able to process this packet.
379 */
380 #define sa_ERR_PACKET -22
382 /**
383 * @def sa_ERR_INV_INT_MEM
384 * SALLD Return Codes -- Invalid internal memory buffer for key storage
385 */
386 #define sa_ERR_INV_INT_MEM -23
388 /**
389 * @def sa_ERR_API_UNSUPPORTED
390 * The API is not supported by this generation of SASS
391 */
392 #define sa_ERR_API_UNSUPPORTED -24
394 /**
395 * @def sa_ERR_PKA_OP_UNSUPPORTED
396 * The required PKA operation is not supported by this generation of PKA module
397 */
398 #define sa_ERR_PKA_OP_UNSUPPORTED -25
400 /**
401 * @def sa_ERR_PKA_NOT_READY
402 * Some PKA operation in in progress and it is not ready for new operation.
403 */
404 #define sa_ERR_PKA_NOT_READY -26
406 /**
407 * @def sa_ERR_PKA_OP_ERROR
408 * The PKA operation return error.
409 */
410 #define sa_ERR_PKA_OP_ERROR -27
412 /**
413 * @def sa_ERR_PKA_INVALID_STATE
414 * PKA API is invoked at inavlid state.
415 */
416 #define sa_ERR_PKA_INVALID_STATE -28
418 /**
419 * @def sa_ERR_PKA_WORKSPACE_ERROR
420 * There is no enough workspace to execute the PKA complex operaion.
421 */
422 #define sa_ERR_PKA_WORKSPACE_ERROR -29
424 /**
425 * @def sa_ERR_PKA_DOWNLOAD_FAIL
426 * The PKA Firmware download failure.
427 */
428 #define sa_ERR_PKA_DOWNLOAD_FAIL -30
430 /**
431 * @def sa_PKA_OP_IN_PROGRESS
432 * The current PKA operation is still in progress.
433 */
434 #define sa_PKA_OP_IN_PROGRESS 1
436 /**
437 * @def sa_PKA_OP_CONTINUE
438 * The current PKA operation is completed and it has started the next operation in sequence.
439 */
440 #define sa_PKA_OP_CONTINUE 2
442 /**
443 * @def sa_PKA_OP_COMPLETE
444 * All PKA operations in sequence are completed and the final results are ready.
445 */
446 #define sa_PKA_OP_COMPLETE sa_ERR_OK
448 /**
449 * @def sa_MAX_PS_AI_WORD_COUNT
450 * upto 12 32-bit words of 'personalizatoin string' and 'additional input' used for
451 * SP-800-90A AES-256 DRBG
452 */
454 #define sa_MAX_PS_AI_WORD_COUNT 12
457 /*@}*/
458 /** @} */
460 /**
461 * @defgroup SecurityProtocolTypes Security Protocol Types
462 * @ingroup salld_api_constants
463 * @{
464 *
465 * @name Security Protocol Types
466 *
467 * Definition of Security Protocol Types of the packets to
468 * be processed in the SALLD channel
469 *
470 */
471 /*@{*/
472 typedef enum {
473 sa_PT_NULL = 0, /**< No protocol: Data mode */
474 sa_PT_SRTP, /**< Security RTP */
475 sa_PT_SRTCP, /**< Security RTCP */
476 sa_PT_IPSEC_AH, /**< IPSEC AH mode */
477 sa_PT_IPSEC_ESP, /**< IPSEC ESP mode */
478 sa_PT_3GPP_AC /**< 3GPP Air Ciphering */
479 } Sa_SecProto_e;
480 /*@}*/
481 /** @} */
483 /**
484 * @defgroup CipherModes Cipher Modes
485 * @ingroup salld_api_constants
486 * @{
487 *
488 * @name Cipher Modes
489 *
490 * Definition of Cipher Modes used by the SA sub-engines
491 *
492 */
493 /*@{*/
494 typedef enum {
495 sa_CipherMode_NULL = 0, /**< No encryption */
496 sa_CipherMode_AES_CTR, /**< AES Counter mode */
497 sa_CipherMode_AES_F8, /**< AES F8 mode */
498 sa_CipherMode_AES_CBC, /**< AES CBC mode */
499 sa_CipherMode_DES_CBC, /**< DES CBC mode */
500 sa_CipherMode_3DES_CBC, /**< 3DES CBC mode */
501 sa_CipherMode_CCM, /**< Counter with CBC-MAC mode */
502 sa_CipherMode_GCM, /**< Galois Counter mode */
503 sa_CipherMode_GSM_A53, /**< 3GPP GSM A5/3 encryption: Key stream generation */
504 sa_CipherMode_ECSD_A53, /**< 3GPP ECSD A5/3 encryption: Key stream generation */
505 sa_CipherMode_GEA3, /**< 3GPP GPRA encryption: Key stream generation */
506 sa_CipherMode_KASUMI_F8, /**< 3GPP Kasumi F8 mode */
507 sa_CipherMode_SNOW3G_F8, /**< 3GPP Snow3G F8 mode */
508 sa_CipherMode_ZUC_F8, /**< 3GPP ZUC F8 mode (SASS_GEN2 only)*/
509 sa_CipherMode_LAST
510 } Sa_CipherMode_e;
511 /*@}*/
512 /** @} */
514 /**
515 * @defgroup AuthModes Authentication Modes
516 * @ingroup salld_api_constants
517 * @{
518 *
519 * @name Authentication Modes
520 * Definition of Authentication Modes used by the SA sub-engines
521 */
522 /*@{*/
523 typedef enum {
524 sa_AuthMode_NULL = 0, /**< No idviudal Authentication */
525 sa_AuthMode_MD5 = sa_CipherMode_LAST, /**< MD5 mode */
526 sa_AuthMode_SHA1, /**< SHA1 mode */
527 sa_AuthMode_SHA2_224, /**< 224-bit SHA2 mode */
528 sa_AuthMode_SHA2_256, /**< 256-bit SHA2 mode */
529 sa_AuthMode_SHA2_384, /**< 384-bit SHA2 mode
530 @note: This mode is used at Data Mode only for SA2_UL */
531 sa_AuthMode_SHA2_512, /**< 512-bit SHA2 mode
532 @note: This mode is used at Data Mode only for SA2_UL */
533 sa_AuthMode_HMAC_MD5, /**< HMAC with MD5 mode */
534 sa_AuthMode_HMAC_SHA1, /**< HMAC with SHA1 mode */
535 sa_AuthMode_HMAC_SHA2_224, /**< HMAC with 224-bit SHA2 mode */
536 sa_AuthMode_HMAC_SHA2_256, /**< HMAC with 256-bit SHA2 mode */
537 sa_AuthMode_HMAC_SHA2_384, /**< HMAC with 224-bit SHA mode
538 @note: This mode is used at Data Mode only for SA2_UL */
539 sa_AuthMode_HMAC_SHA2_512, /**< HMAC with 256-bit SHA mode
540 @note: This mode is used at Data Mode only for SA2_UL */
541 sa_AuthMode_GMAC, /**< Galois Message Authentication Code mode */
542 sa_AuthMode_GMAC_AH, /**< Galois Message Authentication Code mode for IPSEC AH operation
543 @note: This mode is used at Data Mode only */
544 sa_AuthMode_CMAC, /**< Cipher-based Message Authentication Code mode */
545 sa_AuthMode_CBC_MAC, /**< Cipher Block Chaining - Message Authentication Code mode */
546 sa_AuthMode_AES_XCBC, /**< AES Extended Cipher Block Chaining - Message Authentication Code mode */
547 sa_AuthMode_KASUMI_F9, /**< 3GPP Kasumi F9 mode */
548 sa_AuthMode_SNOW3G_F9, /**< 3GPP Snow3G F9 mode (SASS_GEN2 only) */
549 sa_AuthMode_ZUC_F9 /**< 3GPP ZUC F9 mode (SASS_GEN2 only) */
550 } Sa_AuthMode_e;
551 /*@}*/
552 /** @} */
554 /**
555 * @ingroup salld_api_structures
556 * @brief Specification of Sa_ChanHandle
557 * The Sa_ChanHandle is used to identify a SALLD channel instance
558 */
559 typedef void* Sa_ChanHandle;
561 /**
562 * @defgroup saSizeConfigCtrlBit SA Size Configuration Control Bit Definitions
563 * @ingroup salld_api_constants
564 * @{
565 *
566 * @name SA Size Configuration Control Bit Definitions
567 *
568 * Bitmap definition of the ctrlBitMap in Sa_ChanSizeCfg_t and Sa_SizeCfg_t.
569 *
570 */
571 /*@{*/
572 /**
573 * @def sa_SIZE_CONFIG_CREATE_SHADOW_INST
574 * Control Info -- 0:Do not create shadow instance (refer to @ref appendix2)
575 * 1:Create Shadow instance for mixed-endianness operation
576 */
578 #define sa_SIZE_CONFIG_CREATE_SHADOW_INST 0x0001
581 /**
582 * @def sa_SIZE_CONFIG_SASS_GEN2
583 * Control Info -- 0:First generation Security Accelerator Sub-System (SASS)
584 * 1:Second generattion SASS at more advanced keystone2 devices such as Lamarr and Edison
585 * (TBD: to be replaced with part number)
586 */
588 #define sa_SIZE_CONFIG_SASS_GEN2 0x0002
590 /**
591 * @def sa_SIZE_CONFIG_SASS_UL_GEN2
592 * Control Info -- 0:First generation Security Accelerator Ultra Lite Sub-System (SAUL)
593 * 1:Second generattion Security Aaccelerator Ultra Lite Sub-System (SA2_UL)
594 * at more advanced keystone3 devices such as Maxwell
595 */
597 #define sa_SIZE_CONFIG_SASS_UL_GEN2 0x0003
600 /*@}*/
601 /** @} */
603 /**
604 * @ingroup salld_api_structures
605 * @brief SALLD channel size configuration structure
606 *
607 * DESCRIPTION: Data structure that defines memory requirements for SALLD channel instance
608 *
609 */
610 typedef struct {
611 Sa_SecProto_e protocolType; /**< Security protocol type as defined by @ref SecurityProtocolTypes */
612 int cacheLineSize; /**< Specify the size of cache line of the memory where the channel buffers will reside.
613 Set this variable to 0 if this channel is not shared among multiple cores
614 @note cacheLineSize should be the larger of cache line sizes amoung mixed processors */
615 uint16_t ctrlBitMap; /**< Various configuration information as specified at @ref saSizeConfigCtrlBit */
616 } Sa_ChanSizeCfg_t;
618 /**
619 * @ingroup salld_api_structures
620 * @brief SALLD Channel Configuration structure
621 *
622 * Data structure providing configuration information in Sa_chanInit()
623 *
624 */
625 typedef struct {
626 uint32_t ID; /**< User specified channel ID */
627 Sa_ChanSizeCfg_t sizeConfig; /**< SALLD memory allocation requirement structure */
628 uint16_t engSelect; /**< User selected encryption/authentication engine set number,
629 valid only when Sa_Config_t.engSelMode is sa_EngSelMode_USERSPECIFIED */
630 } Sa_ChanConfig_t;
632 /**
633 * @ingroup salld_api_structures
634 * @brief SRTP Configuration Parameters structure
635 *
636 * Data structure defines the SRTP specific configuration parameters excluding the keys
637 *
638 */
639 typedef struct {
640 uint16_t masterKeySize; /**< Specify the size of the master key in bytes */
641 uint16_t masterSaltSize; /**< Specify the size of the master salt in bytes */
642 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key in bytes */
643 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
644 uint16_t sessionSaltSize; /**< Specify the size of the session salt in bytes */
645 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
646 } Sa_SrtpConfigParams_t;
648 /**
649 * @defgroup saIpsecTransportTypes IPSEC Transport Types
650 * @ingroup salld_api_constants
651 * @{
652 *
653 * @name IPSEC Transport Types
654 *
655 * Parameter transportType of Sa_IpsecConfigParams_t should be set to
656 * one of these transport types.
657 */
658 /*@{*/
659 typedef enum {
660 sa_IPSEC_TRANSPORT_TRANSPORT = 0, /**< Trasport mode */
661 sa_IPSEC_TRANSPORT_TUNNEL /**< Tunnel mode */
662 } Sa_IpsecTransportType_e;
663 /*@}*/
664 /** @} */
666 /**
667 * @defgroup saIpsecConfigCtrlBit IPSEC Configuration Control Bit Definitions
668 * @ingroup salld_api_constants
669 * @{
670 *
671 * @name IPSEC Configuration Control Bit Definitions
672 *
673 * Bitmap definition of the ctrlBitMap in salldInpsecConfigParams_t.
674 *
675 */
676 /*@{*/
677 /**
678 * @def sa_IPSEC_CONFIG_ESN
679 * Control Info -- 0:Disable Extended Sequence Number
680 * 1:Enable Extended Sequence Number
681 */
682 #define sa_IPSEC_CONFIG_ESN 0x0001
683 /**
684 * @def sa_IPSEC_CONFIG_PERMANENT_SC
685 * Control Info -- 0:The corresponding security context is marked as second tier
686 * 1:The corresponding security context ia marked as first tier so that it will
687 * not be evicted automatically.
688 */
689 #define sa_IPSEC_CONFIG_PERMANENT_SC 0x0002
690 /*@}*/
691 /** @} */
693 /**
694 * @ingroup salld_api_structures
695 * @brief IPSEC Configuration Parameters structure
696 *
697 * Data structure defines the IPSEC specific configuration parameters excluding the keys
698 *
699 */
700 typedef struct {
701 uint16_t transportType; /**< Specify the transport Type as defined at @ref saIpsecTransportTypes */
702 uint16_t ctrlBitMap; /**< Various control information as specified at @ref saIpsecConfigCtrlBit */
703 uint16_t encryptionBlockSize; /**< Specify the encryption block size
704 1: Stream encryption and no alignment requirement
705 4: AES-CTR or other stream-like encryption with 4-byte
706 alignment
707 block size: block encryption algorithm */
708 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key in bytes */
709 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
710 uint16_t sessionSaltSize; /**< Specify the size of the session salt in bytes */
711 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
712 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
713 uint16_t nextHdr; /**< Specify the next protocol header */
714 /**< @note: This parameter is no longer used. */
715 uint32_t spi; /**< Specify the SPI (Security Parameter Index) */
716 uint32_t esnLo; /**< Specify the initial value of the (extended) sequence Number (lower 32-bit) */
717 uint32_t esnHi; /**< Specify the initial value of the extended sequence Number (upper 32-bit) */
718 } Sa_IpsecConfigParams_t;
720 /**
721 * @defgroup AcPduTypes Air Ciphering PDU Types
722 * @ingroup salld_api_constants
723 * @{
724 *
725 * @name Air Ciphering PDU Types
726 *
727 * Definition of Air Ciphering PDU Types supported in SA
728 * Parameter pduType of Sa_AcConfigParams_t should be set to
729 * one of these types. Refer to @ref appendix1 for detailed
730 * description
731 *
732 */
733 /*@{*/
734 typedef enum {
735 sa_AcPduType_GSM = 0, /**< All GSM PDUs */
736 sa_AcPduType_WCDMA_TMD, /**< WCDMA MAC TMD */
737 sa_AcPduType_WCDMA_UMD, /**< WCDMA RLC UMD */
738 sa_AcPduType_WCDMA_AMD, /**< WCDMA RLC AMD */
739 sa_AcPduType_LTE, /**< LTE PDCP PDUs */
740 sa_AcPduType_LTE_CP /**< PDCP Control Plane Data Uint for SRBs */
741 } Sa_AcPduType_e;
742 /*@}*/
743 /** @} */
745 /**
746 * @defgroup SALLDAcConfigCtrlBit AC Configuration Control Bit Definitions
747 * @ingroup salld_api_constants
748 * @{
749 *
750 * @name AC Configuration Control Bit Definitions
751 *
752 * Bitmap definition of the ctrlBitMap in Sa_AcConfigParams_t.
753 *
754 */
755 /*@{*/
756 /**
757 * @def sa_AC_CONFIG_BEARER_MASK
758 * Control Info -- 5-bit or 8-bit Bearer mask
759 */
760 #define sa_AC_CONFIG_BEARER_MASK 0x00FF
761 /**
762 * @def sa_AC_CONFIG_DIR
763 * Control Info -- 0:UE to RNC(uplink)
764 * 1:RNC to UE(downlink)
765 */
766 #define sa_AC_CONFIG_DIR 0x0100
767 /**
768 * @def sa_AC_CONFIG_COPY_COUNTC
769 * Control Info -- 1: Copy Count-C into the timestamp field within CPPI Descriptor for reference
770 * 0: Otherwise
771 */
772 #define sa_AC_CONFIG_COPY_COUNTC 0x0200
774 /**
775 * @def sa_AC_CONFIG_COUNTC_BY_APP
776 * Control Info -- 1: Count-C is provided by application.
777 * 0: Count-C is incremented and stored at SASS
778 *
779 * @note: This flag is only applicable for the to-air traffic when PDU type is set to LTE
780 * where the count-C is maintained by SASS by default.
781 * This flag may be used to inform SASS that the count-C will be provided by application
782 * for LTE data traffic in slow path.
783 */
784 #define sa_AC_CONFIG_COUNTC_BY_APP 0x0400
786 /**
787 * @def sa_AC_CONFIG_KEY_IN_SCRATCH
788 * Control Info -- 0:key is copied into security context by lld
789 * 1:key is copied into scratch memory by lld
790 * @note: This feature is not supported for KeyStone devices such as C6678
791 */
792 #define sa_AC_CONFIG_KEY_IN_SCRATCH 0x0800
794 /*@}*/
795 /** @} */
797 /**
798 * @ingroup salld_api_structures
799 * @brief AC (Air Ciphering) Configuration Parameters structure
800 *
801 * Data structure defines the AC specific configuration parameters excluding the keys
802 *
803 */
805 typedef struct {
806 uint32_t countC; /**< Specify the high bits, HFN, for the frame Counter
807 WCDMA RLC AM: the high 20 bits are used
808 WCDMA RLC UM: the high 25 bits are used
809 WCDMA RLC TM: the high 25 bits are used
810 LTE: All 32-bit is used as Count-C
811 GSM: Not used */
812 uint32_t fresh; /**< Specify the 32-bit random number (fresh) required
813 for some integrity check algorithms */
814 uint32_t ivLow26; /**< Specify the low 26-bit value of the initialization vector */
815 uint16_t pduType; /**< Specify the Air Ciphering PDU Type as defined at @ref Sa_AcPduType_e */
816 uint16_t ctrlBitMap; /**< Various control information as specified at @ref SALLDAcConfigCtrlBit */
817 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key (Kc) in bytes
818 Note: The LLD may expand the key stream based on the encryption mode */
819 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
820 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
821 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
822 } Sa_AcConfigParams_t;
824 /**
825 * @defgroup SALLDDmConfigCtrlBit Data Mode Configuration Control Bit Definitions
826 * @ingroup salld_api_constants
827 * @{
828 *
829 * @name Data Mode Configuration Control Bit Definitions
830 *
831 * Bitmap definition of the ctrlBitMap in Sa_DmConfigParams_t.
832 *
833 */
834 /*@{*/
835 /**
836 * @def sa_DM_CONFIG_SELECT_AIR_CIPHER_ENG
837 * Control Info -- 1: indicate selection of Air Cipher engine in data mode
838 * 0: use Encryption engine (default)
839 * @note: There are Encryption Engine and Air Cipher Engine in SASS. There are
840 * certain types of algorithms such as AES_CTR which both of these engines are
841 * capable of executing. By default the data mode selects to use the encryption
842 * engine for the algorithms such as AES_CTR. To seperate the Air Cipher traffic
843 * from the IPSec traffic, application may select the air cipher engine
844 * for the encryption by setting this bit.
845 *
846 * For devices such as K2G (NSS_LITE) which do not have air cipher engine
847 * setting this bit would cause error during datamode channel control configuration.
848 *
849 * This bit is supported for SA LLD releases version 3.0.0.15 or higher
850 */
851 #define sa_DM_CONFIG_SELECT_AIR_CIPHER_ENG ((uint16_t) (0x0001U))
853 /**
854 * @def sa_DM_CONFIG_PROMOTE_NONSECURE
855 * Control Info -- 1: promotion of normal world packet to secure packet
856 * intended to land in the secure memory (only for sa2ul)
857 * 0: no promotion
858 * @note: Promotion of non-secure packet to be secure packet also always requires
859 * the 48-bit SCPTR that comes with the packet to be within the range
860 * of 'SCPTR Promote Range' registers.
861 *
862 * For devices that do not have SA2UL setting this bit would cause no action
863 *
864 */
865 #define sa_DM_CONFIG_PROMOTE_CHANNEL ((uint16_t) (0x0002U))
867 /**
868 * @def sa_DM_CONFIG_DEMOTE_SECURE
869 * Control Info -- 1: demotion of secure packet to normal world packet
870 * intended to land in the secure memory (only for sa2ul)
871 * 0: no demotion
872 *
873 * For devices that do not have SA2UL setting this bit would cause no action
874 *
875 */
876 #define sa_DM_CONFIG_DEMOTE_CHANNEL ((uint16_t) (0x0004U))
878 /**
879 * @def sa_DM_CONFIG_USE_SECURE_CTX_FOR_NON_SECURE_CHANNEL
880 * Control Info -- 1: a normal world packet may use secure context
881 * 0: non-secure packet for this context can't use secure context
882 *
883 * For devices that do not have SA2UL setting this bit would cause no action
884 *
885 */
886 #define sa_DM_CONFIG_USE_SECURE_CTX_FOR_NON_SECURE_CHANNEL ((uint16_t) (0x0008U))
889 /*@}*/
890 /** @} */
892 /**
893 * @ingroup salld_api_structures
894 * @brief Data Mode Configuration Parameters structure
895 *
896 * Data structure defines the Data Mode specific configuration parameters excluding the keys.
897 *
898 * Due to hardware limiations in IP, below restrictions apply :
899 *
900 @verbatim
901 ---------------------------------------------------------------------------
902 | Cipher Mode | Restriction |
903 ---------------------------------------------------------------------------
904 | - sa_CipherMode_CCM | - (IV Size + Salt Size) should not exceed 13 |
905 | | - AAD size should not exceed 14 |
906 | | - authentication mode should be null |
907 ---------------------------------------------------------------------------
908 | - sa_CipherMode_GCM | - (IV Size + Salt Size) should be 12 |
909 | | - AAD size should not exceed 16 |
910 | | - authentication mode should be null |
911 ---------------------------------------------------------------------------
912 | - sa_CipherMode_DES_CBC | - (IV Size should be 8 |
913 | | - Salt size should be 0 |
914 ---------------------------------------------------------------------------
915 | - sa_CipherMode_3DES_CBC | - (IV Size should be 8 |
916 | | - Salt size should be 0 |
917 ---------------------------------------------------------------------------
918 | - sa_CipherMode_KASUMI_F8| - (IV Size should be 8 |
919 | | |
920 ---------------------------------------------------------------------------
921 | - sa_CipherMode_SNOW3G_F8| - (IV Size should be 16 |
922 | | |
923 ---------------------------------------------------------------------------
925 ---------------------------------------------------------------------------
926 | Auth Mode | Restriction |
927 ---------------------------------------------------------------------------
928 | - sa_AuthMode_GMAC | - (IV Size + Salt Size) should be 12 |
929 | | - AAD size should not exceed 16 |
930 | | - cipher mode should be null |
931 ---------------------------------------------------------------------------
932 | - sa_AuthMode_GMAC_AH | - (IV Size should be 8 |
933 | | - Salt size should be 4 |
934 | | - cipher mode should be null |
935 ---------------------------------------------------------------------------
936 | - sa_AuthMode_KASUMI_F9 | - (IV Size should be 8 |
937 | | |
938 ---------------------------------------------------------------------------
939 @endverbatim
940 */
941 typedef struct {
942 uint16_t ctrlBitMap; /**< Various control information as specified at @ref SALLDDmConfigCtrlBit */
943 uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key in bytes */
944 uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
945 uint16_t sessionSaltSize; /**< Specify the size of the session salt used in the GCM/CCM operation in bytes */
946 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
947 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
948 uint16_t aadSize; /**< Specify the size of the additional authenticated data in bytes used in CCM and GCM modes */
949 uint16_t enc; /**< TRUE: Encryption(To-Air); FALSE: Decryption (From-Air)*/
950 uint16_t enc1st; /**< TRUE: Perform encryption first; FALSE: Perform authentication first */
951 #if defined(NSS_LITE2)
952 uint8_t priv; /**< Specify the priv for the security context creation */
953 uint8_t privId; /**< Specify the priv ID for the security context to checking with incoming packets to match */
954 #endif
955 } Sa_DataModeConfigParams_t;
957 /**
958 * @ingroup salld_api_structures
959 * @brief SALLD Protocol-specfic Configuration Parameters structure
960 *
961 * Data structure defines the security protocol specific configuration parameters
962 *
963 */
964 typedef union {
965 Sa_SrtpConfigParams_t srtp; /**< Specify the configuration parameters for SRTP */
966 Sa_IpsecConfigParams_t ipsec; /**< Specify the configuration parameters for IPSEC */
967 Sa_AcConfigParams_t ac; /**< Specify the configuration parameters for Air Ciphering */
968 Sa_DataModeConfigParams_t data; /**< Specify the configuration parameters for Data Mode */
969 } Sa_ProtocolConfigParams_t;
971 /**
972 * @defgroup SALLDDestInfoCtrlBit SALLD Destination Info Control Bit Definitions
973 * @ingroup salld_api_constants
974 * @{
975 *
976 * @name SALLD Destination Info Control Bit Definitions
977 * Bitmap definition of the ctrlBitfield in Sa_DestInfo_t
978 * It allows selective enabling/disabling of specific SALLD operations
979 *
980 */
981 /*@{*/
982 /**
983 * @def sa_DEST_INFO_CTRL_USE_LOC_DMA
984 * Control Info -- Set: Use Local DMA
985 * Clear: Use Global DMA (defAult)
986 *
987 * There are Network Sub-System (NSS) internal DMA resources including CPPI and QMSS which can be used to transfer packets within
988 * 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.
989 *
990 * @note: This feature is only supported at the second generation NSS devices.
991 */
992 #define sa_DEST_INFO_CTRL_USE_LOC_DMA 0x01
993 /*@}*/
994 /** @} */
997 /**
998 * @ingroup salld_api_structures
999 * @brief SALLD Destination Info structure
1000 *
1001 * Data structure defines the destination parameters which are used
1002 * by SASS to deliver the processed packets to the desired destination
1003 *
1004 */
1005 typedef struct {
1006 uint8_t ctrlBitfield; /**< Control Bit Map to specify destination related operations such as local DMA
1007 as defined at @ref SALLDDestInfoCtrlBit */
1009 uint16_t flowID; /**< Specify the CPPI Flow ID */
1010 uint16_t queueID; /**< Specify the 16-bit destination Queue ID (OR Ring ID for SA2UL) */
1011 uint32_t swInfo0; /**< User-defined channel-specific parameter which will be placed in SwInfo0 for packets from SA */
1012 uint32_t swInfo1; /**< User-defined channel-specific parameter which will be placed in SwInfo1 for packets from SA */
1013 } Sa_DestInfo_t;
1015 /**
1016 * @ingroup salld_api_structures
1017 * @brief SALLD General Configuration Parameters structure
1018 *
1019 * Data structure defines the general configuration parameters excluding the keys and related
1020 * re-key parameters
1021 *
1022 */
1023 typedef struct {
1024 Sa_CipherMode_e cipherMode; /**< Specify the cipher mode as defined at @ref CipherModes */
1025 Sa_AuthMode_e authMode; /**< Specify the authentication mode as defined at @ref AuthModes */
1026 Sa_DestInfo_t destInfo; /**< Specify the post-SA destination information */
1027 Sa_ProtocolConfigParams_t params; /**< Specify the protocol-specific configuration parameters */
1028 } Sa_GenConfigParams_t;
1030 /**
1031 * @defgroup SALLDCtrlInfoValidBit SALLD General Control Info Valid Bit Definitions
1032 * @ingroup salld_api_constants
1033 * @{
1034 *
1035 * @name SALLD General Control Info Valid Bit Definitions
1036 * Bitmap definition of the validBitfield in Sa_GenCtrlInfo_t.
1037 * It allows selective control parameters
1038 */
1039 /*@{*/
1040 /**
1041 * @def sa_CONTROLINFO_VALID_CTRL_BITMAP
1042 * Control Info -- ctrlBitfield
1043 */
1044 #define sa_CONTROLINFO_VALID_CTRL_BITMAP 0x0001
1045 /**
1046 * @def sa_CONTROLINFO_VALID_TX_CTRL
1047 * Control Info -- txCtrl
1048 */
1049 #define sa_CONTROLINFO_VALID_TX_CTRL 0x0002
1050 /**
1051 * @def sa_CONTROLINFO_VALID_RX_CTRL
1052 * Control Info -- rtxCtrl
1053 */
1054 #define sa_CONTROLINFO_VALID_RX_CTRL 0x0004
1055 /**
1056 * @def sa_CONTROLINFO_VALID_REPLAY_WIN
1057 * Control Info -- replayWindowSize
1058 */
1059 #define sa_CONTROLINFO_VALID_REPLAY_WIN 0x0008
1060 /*@}*/
1061 /** @} */
1063 /**
1064 * @defgroup SALLDCtrlInfoCtrlBit SALLD General Control Info Control Bit Definitions
1065 * @ingroup salld_api_constants
1066 * @{
1067 *
1068 * @name SALLD General Control Info Control Bit Definitions
1069 * Bitmap definition of the ctrlBitfield in Sa_GenCtrlInfo_t.
1070 * It allows selective enabling/disabling of specific SALLD operations
1071 *
1072 */
1073 /*@{*/
1074 /**
1075 * @def sa_CONTROLINFO_CTRL_TX_ON
1076 * Control Info -- Enable Tx
1077 */
1078 #define sa_CONTROLINFO_CTRL_TX_ON 0x0001
1079 /**
1080 * @def sa_CONTROLINFO_CTRL_RX_ON
1081 * Control Info -- Enable Rx
1082 */
1083 #define sa_CONTROLINFO_CTRL_RX_ON 0x0002
1084 /**
1085 * @def sa_CONTROLINFO_CTRL_TX_RX_MASK
1086 * Control Info -- Tx/Rx Control
1087 * Bit Mask
1088 */
1089 #define sa_CONTROLINFO_CTRL_TX_RX_MASK 0x0003
1090 /**
1091 * @def sa_CONTROLINFO_CTRL_SW_ONLY
1092 * Control Info -- Software support only.
1093 * It is used for the protocols which are not supported by the SA
1094 * firmware such as SRTCP.
1095 */
1096 #define sa_CONTROLINFO_CTRL_SW_ONLY 0x0008
1097 /**
1098 * @def sa_CONTROLINFO_CTRL_OP_MASK
1099 * Control Info -- Operation Control
1100 * Bit Mask
1101 */
1102 #define sa_CONTROLINFO_CTRL_OP_MASK 0x000b
1103 /*@}*/
1104 /** @} */
1106 /**
1107 * @ingroup salld_api_structures
1108 * @brief SALLD General Control Information structure
1109 *
1110 * Data structure defines the general control information of the security channel excluding the keys
1111 * and related re-key parameters
1112 *
1113 */
1114 typedef struct {
1115 uint16_t validBitfield; /**< Specify valid parameters as defined at @ref SALLDCtrlInfoValidBit */
1116 uint16_t ctrlBitfield; /**< Control Bit Map to specify tx/rx and other operations
1117 as defined at @ref SALLDCtrlInfoCtrlBit */
1118 Sa_GenConfigParams_t txCtrl; /**< Specify the general configuration parameters in Tx
1119 (to-network) direction */
1120 Sa_GenConfigParams_t rxCtrl; /**< Specify the general configuration parameters in Rx
1121 (from-network) direction */
1122 uint16_t replayWindowSize; /**< Specify the size of the replay window
1123 (SRTP 64 IPSEC 64:128) */
1124 } Sa_GenCtrlInfo_t;
1126 /**
1127 * @defgroup SALLDSrtpKeyCtrlInfo SALLD SRTP Key Control Info Bit Definitions
1128 * @ingroup salld_api_constants
1129 * @{
1130 *
1131 * @name SRTP Key Control Info Bit Definitions
1132 *
1133 * Bitmap definition of the ctrlBitfield in Sa_SrtpKeyParams_t.
1134 */
1135 /*@{*/
1136 /**
1137 * @def sa_SRTP_KEY_CTRL_MASTER_KEY
1138 * Control Info -- Set: MASTER_KEY available
1139 */
1140 #define sa_SRTP_KEY_CTRL_MASTER_KEY 0x0001
1141 /**
1142 * @def sa_SRTP_KEY_CTRL_MASTER_SALT
1143 * Control Info -- Set: MASTER_SALT available
1144 */
1145 #define sa_SRTP_KEY_CTRL_MASTER_SALT 0x0002
1146 /**
1147 * @def sa_SRTP_KEY_CTRL_KEY_DERIVE_RATE
1148 * Control Info -- Set: key derivation rate available
1149 */
1150 #define sa_SRTP_KEY_CTRL_KEY_DERIVE_RATE 0x0004
1151 /**
1152 * @def sa_SRTP_KEY_CTRL_KEY_LIFETIME
1153 * Control Info -- Set: key lifetime available
1154 */
1155 #define sa_SRTP_KEY_CTRL_KEY_LIFETIME 0x0008
1156 /**
1157 * @def sa_SRTP_KEY_CTRL_ROC
1158 * Control Info -- Set: Initial ROC is available
1159 */
1160 #define sa_SRTP_KEY_CTRL_ROC 0x0010
1162 /**
1163 * @def sa_SRTP_KEY_CTRL_MKI
1164 * Control Info -- Set: MKI available
1165 */
1166 #define sa_SRTP_KEY_CTRL_MKI 0x0020
1167 /**
1168 * @def sa_SRTP_KEY_CTRL_KEY_TYPE_FROM_TO
1169 * Control Info -- Set: From To Key
1170 * Clear: MKI Key
1171 */
1172 #define sa_SRTP_KEY_CTRL_KEY_TYPE_FROM_TO 0x0040
1173 /*@}*/
1174 /** @} */
1176 /**
1177 * @ingroup salld_api_structures
1178 * @brief SRTP Key Information structure
1179 *
1180 * Data structure defines the SRTP Key related parameters
1181 *
1182 */
1183 typedef struct {
1184 uint16_t ctrlBitfield; /**< Specify the Key types and other control information as defined at @ref SALLDSrtpKeyCtrlInfo */
1185 uint8_t* masterKey; /**< Specify the master key */
1186 uint8_t* masterSalt; /**< Specify the master Salt */
1187 uint16_t derivRate; /**< Specify the key derivation rate in n of 2^n format (where 0 <= n <= 24)
1188 if not set then use default value, i.e no key derivation */
1189 uint16_t keyLifeTimeMsw; /**< Specify the maximum number of packets allowed for the master
1190 key combination */
1191 uint32_t keyLifeTimeLsw; /**< Specify the maximum number of packets allowed for the master
1192 key combination */
1193 uint32_t roc; /**< SRTP: Specify the initial value of the rollover counter
1194 SRTCP: Specify the initial index at the tx packet */
1195 uint32_t fromEsnMsw; /**< Specify the starting 48-bit extended sequence number
1196 of the specified From-To keys */
1197 uint16_t fromEsnLsw; /**< Specify the starting 48-bit extended sequence number
1198 of the specified From-To keys */
1199 uint32_t toEsnMsw; /**< Specify the last 48-bit extended sequence number
1200 of the specified From-To keys */
1201 uint16_t toEsnLsw; /**< Specify the last 48-bit extended sequence number
1202 of the specified From-To keys */
1203 uint16_t mkiSize; /**< Specify the size of the MKI in bytes */
1204 uint32_t mki; /**< Specify the MKI value */
1205 } Sa_SrtpKeyParams_t;
1207 /**
1208 * @ingroup salld_api_constants
1209 * @brief Define the maximum key size supported by SASS
1210 */
1211 #if defined(NSS_LITE2)
1212 #define SALLD_MAX_KEY_SIZE 64
1213 #else
1214 #define SALLD_MAX_KEY_SIZE 32
1215 #endif
1217 /**
1218 * @defgroup SALLDIpsecKeyCtrlInfo SALLD IPSEC Key Control Info Bit Definitions
1219 * @ingroup salld_api_constants
1220 * @{
1221 *
1222 * @name IPSEC Key Control Info Bit Definitions
1223 *
1224 * Bitmap definition of the ctrlBitfield in Sa_IpsecKeyParams_t.
1225 */
1226 /*@{*/
1227 /**
1228 * @def sa_IPSEC_KEY_CTRL_ENC_KEY
1229 * Control Info -- Set: ENC_KEY available
1230 */
1231 #define sa_IPSEC_KEY_CTRL_ENC_KEY 0x0001
1232 /**
1233 * @def sa_IPSEC_KEY_CTRL_MAC_KEY
1234 * Control Info -- Set: MAC_KEY available
1235 */
1236 #define sa_IPSEC_KEY_CTRL_MAC_KEY 0x0002
1237 /**
1238 * @def sa_IPSEC_KEY_CTRL_SALT
1239 * Control Info -- Set: Session Salt available
1240 */
1241 #define sa_IPSEC_KEY_CTRL_SALT 0x0004
1242 /*@}*/
1243 /** @} */
1245 /**
1246 * @ingroup salld_api_structures
1247 * @brief IPSEC Key Information structure
1248 *
1249 * Data structure defines the IPSEC Key related parameters
1250 *
1251 */
1252 typedef struct {
1253 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information as defined at @ref SALLDIpsecKeyCtrlInfo */
1254 uint8_t* sessionEncKey; /**< Specify the session encryption key */
1255 uint8_t* sessionAuthKey; /**< Specify the session authentication key */
1256 uint8_t* sessionSalt; /**< Specify the session salt */
1257 } Sa_IpsecKeyParams_t;
1259 /**
1260 * @defgroup SALLDAcKeyCtrlInfo SALLD AC Key Control Info Bit Definitions
1261 * @ingroup salld_api_constants
1262 * @{
1263 *
1264 * @name Air Ciphering Key Control Info Bit Definitions
1265 *
1266 * Bitmap definition of the ctrlBitfield in Sa_AcKeyParams_t.
1267 */
1268 /*@{*/
1269 /**
1270 * @def sa_AC_KEY_CTRL_ENC_KEY
1271 * Control Info -- Set: ENC_KEY available
1272 */
1273 #define sa_AC_KEY_CTRL_ENC_KEY 0x0001
1274 /**
1275 * @def sa_AC_KEY_CTRL_MAC_KEY
1276 * Control Info -- Set: MAC_KEY available
1277 */
1278 #define sa_AC_KEY_CTRL_MAC_KEY 0x0002
1279 /*@}*/
1280 /** @} */
1282 /**
1283 * @ingroup salld_api_structures
1284 * @brief Air Ciphering Key Information structure
1285 *
1286 * Data structure defines the Air Ciphering Key related parameters
1287 *
1288 */
1289 typedef struct {
1290 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information as defined at @ref SALLDAcKeyCtrlInfo */
1291 uint8_t* sessionEncKey; /**< Specify the session encryption key */
1292 uint8_t* sessionAuthKey; /**< Specify the session authentication key */
1293 } Sa_AcKeyParams_t;
1295 /**
1296 * @defgroup SALLDDataModeKeyCtrlInfo SALLD Data Mode Key Control Info Bit Definitions
1297 * @ingroup salld_api_constants
1298 * @{
1299 *
1300 * @name Data Mode Key Control Info Bit Definitions
1301 *
1302 * Bitmap definition of the ctrlBitfield in Sa_DataModeKeyParams_t.
1303 */
1304 /*@{*/
1305 /**
1306 * @def sa_DATA_MODE_KEY_CTRL_ENC_KEY
1307 * Control Info -- Set: ENC_KEY available
1308 */
1309 #define sa_DATA_MODE_KEY_CTRL_ENC_KEY 0x0001
1310 /**
1311 * @def sa_DATA_MODE_KEY_CTRL_MAC_KEY
1312 * Control Info -- Set: MAC_KEY available
1313 */
1314 #define sa_DATA_MODE_KEY_CTRL_MAC_KEY 0x0002
1315 /**
1316 * @def sa_DATA_MODE_KEY_CTRL_SALT
1317 * Control Info -- Set: SALT available
1318 */
1319 #define sa_DATA_MODE_KEY_CTRL_SALT 0x0004
1320 /*@}*/
1321 /** @} */
1323 /**
1324 * @ingroup salld_api_structures
1325 * @brief Data Mode Key Information structure
1326 *
1327 * Data structure defines the Data Mode Key related parameters
1328 *
1329 */
1330 typedef struct {
1331 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information as defined at @ref SALLDDataModeKeyCtrlInfo */
1332 uint8_t* sessionEncKey; /**< Specify the session encryption key */
1333 uint8_t* sessionAuthKey; /**< Specify the session authentication key */
1334 uint8_t* sessionSalt; /**< Specify the session salt in GCM/CCM only */
1335 } Sa_DataModeKeyParams_t;
1337 /**
1338 * @ingroup salld_api_structures
1339 * @brief Protocol-Specific Key Information structure
1340 *
1341 * Data structure defines the protocol-specific Key related parameters
1342 *
1343 */
1344 typedef union {
1345 Sa_SrtpKeyParams_t srtp; /**< Specify the key related parameters for SRTP/SRTCP */
1346 Sa_IpsecKeyParams_t ipsec; /**< Specify the key related parameters for IPSEC */
1347 Sa_AcKeyParams_t ac; /**< Specify the key related parameters for 3GPP Air Ciphering */
1348 Sa_DataModeKeyParams_t data; /**< Specify the key related parameters in Data Mode */
1349 } Sa_ProtocolKeyParams_t;
1351 /**
1352 * @defgroup SALLDKeyCtrlInfo SALLD Key Control Info Control Bit Definitions
1353 * @ingroup salld_api_constants
1355 * @{
1356 *
1357 * @name SALLD Key Control Info Control Bit Definitions
1358 *
1359 * Bitmap definition of the ctrlBitfield in Sa_KeyCtrlInfo_t.
1360 */
1361 /*@{*/
1362 /**
1363 * @def sa_KEY_CONTROL_TX_KEY_VALID
1364 * Control Info -- TX key is valid
1365 */
1366 #define sa_KEY_CONTROL_TX_KEY_VALID 0x0001
1367 /**
1368 * @def sa_KEY_CONTROL_RX_KEY_VALID
1369 * Control Info -- RX key is valid
1370 */
1371 #define sa_KEY_CONTROL_RX_KEY_VALID 0x0002
1372 /* @} */ /* ingroup */
1373 /** @} */
1375 /**
1376 * @ingroup salld_api_structures
1377 * @brief SALLD Key Control Information structure
1378 *
1379 * Data structure defines the Key related information of the security channel.
1380 * It is used for initial channel configuration and re-key operation.
1381 *
1382 */
1383 typedef struct {
1384 uint16_t ctrlBitfield; /**< Bit Map to specify tx/rx and other operations as
1385 defined at @ref SALLDKeyCtrlInfo */
1386 Sa_ProtocolKeyParams_t txKey; /**< Specify the security key parameters in Tx
1387 (to-network) direction */
1388 Sa_ProtocolKeyParams_t rxKey; /**< Specify the security key parameters in Rx
1389 (from-network) direction */
1390 } Sa_KeyCtrlInfo_t;
1392 /**
1393 * @defgroup salldChanCtrlType SALLD Channel Control Type
1394 * @ingroup salld_api_constants
1395 * @{
1396 *
1397 * @name Channel Control Type
1398 * Definition of channel control types supported by SA LLD
1399 * Parameter ctrlType of Sa_ChanCtrlInfo_t should be set to
1400 * one of these types.
1401 *
1402 */
1403 /*@{*/
1404 typedef enum {
1405 sa_CHAN_CTRL_GEN_CONFIG = 1, /**< Security Channel General Configuration */
1406 sa_CHAN_CTRL_KEY_CONFIG = 2 /**< Security Channel Key Configuration */
1407 } Sa_ChanControlCode_e;
1408 /*@}*/
1409 /** @} */
1411 /**
1412 * @ingroup salld_api_structures
1413 * @brief Channel Control Information structure
1414 *
1415 * Data structure providing control information in Sa_chanControl()
1416 *
1417 */
1418 typedef struct {
1419 uint16_t ctrlType; /**< Specify the channel control type as defined at @ref Sa_ChanControlCode_e */
1420 union {
1421 Sa_GenCtrlInfo_t gen; /**< Specify the general control information */
1422 Sa_KeyCtrlInfo_t key; /**< Specify the key control information */
1423 }ctrlInfo; /**< Contain the control-type specific control information */
1425 } Sa_ChanCtrlInfo_t;
1427 /**
1428 * @defgroup PktErrorCodes SALLD PKT Error Codes
1429 * @ingroup salld_api_constants
1430 * @{
1431 *
1432 * @name SALLD PKT Error Codes
1433 *
1434 * Definitions of the error codes for the packets received from SA
1435 */
1436 /*@{*/
1437 /**
1438 * @def sa_PKT_ERR_OK
1439 * SALLD Packet Error code -- No Error.
1440 */
1441 #define sa_PKT_ERR_OK 0
1442 /**
1443 * @def sa_PKT_ERR_REPLAY_OLD
1444 * SALLD Packet Error code -- Packet rejected by SA because it is out of replay window range.
1445 */
1446 #define sa_PKT_ERR_REPLAY_OLD 1
1447 /**
1448 * @def sa_PKT_ERR_REPLAY_DUP
1449 * SALLD Packet Error code -- Packet rejected by SA because it is duplicated.
1450 */
1451 #define sa_PKT_ERR_REPLAY_DUP 2
1452 /**
1453 * @def sa_PKT_ERR_INVALID_KEY
1454 * SALLD Packet Error code -- Packet rejected by SA because the key in the security
1455 * context is out of date.
1456 */
1457 #define sa_PKT_ERR_INVALID_KEY 3
1458 /**
1459 * @def sa_PKT_ERR_INVALID_MKI
1460 * SALLD Packet Error code -- Packet rejected by SA because the MKI in the security
1461 * context does not match the one in the packet.
1462 */
1463 #define sa_PKT_ERR_INVALID_MKI 4
1464 /**
1465 * @def sa_PKT_ERR_AUTH_FAIL
1466 * SALLD Packet Error code -- Packet rejected by SA because authentication failed.
1467 */
1468 #define sa_PKT_ERR_AUTH_FAIL 5
1469 /*@}*/
1470 /** @} */
1472 /**
1473 * @ingroup salld_api_structures
1474 * @brief SA Packet Error data type
1475 *
1476 * Data type defines the packet error type of all packets to be delivered to SA.
1477 *
1478 */
1479 typedef uint16_t Sa_PktErr_t;
1481 /**
1482 * @defgroup SaPktDir SA Packet Directions
1483 * @ingroup salld_api_constants
1484 * @{
1485 *
1486 * @name SA Packet Directions
1487 *
1488 * Definition of SA Packet Directions used at API @ref Sa_chanGetSwInfo
1489 */
1490 /*@{*/
1491 typedef enum {
1492 sa_PKT_DIR_FROM_NETWORK = 0, /**< Form-network (To-air) packet */
1493 sa_PKT_DIR_TO_NETWORK /**< To-network (From-air) packet */
1494 } Sa_PktDir_t;
1495 /*@}*/
1496 /** @} */
1498 /**
1499 * @ingroup salld_api_constants
1500 * @brief Define the maxmium number of software info parameters at @ref Sa_SWInfo_t.
1501 */
1502 #define sa_MAX_SW_INFO_SIZE 3
1504 /**
1505 * @ingroup salld_api_structures
1506 * @brief SA Software Information structure
1507 *
1508 * Data structure defines the SA-specific software information required for all packets to
1509 * be delivered to SA. It will be provided by the SA LLD based on the channel configuration
1510 * parameters and the security protocols.The software information words should be copied
1511 * to the CPPI Software words area as provided through the CPPI LLD or equivalent component.
1512 *
1513 * for SA2_UL (Ultra Lite Generation 2) devices, size is always 4 and the swInfo[3] would
1514 * hold the first 32 bits of Protocol Specific data of CPPI
1515 */
1516 typedef struct {
1517 uint16_t size; /**< Specify the software info size in 32-bit words */
1518 uint32_t swInfo[sa_MAX_SW_INFO_SIZE]; /**< Specify the software information for SA */
1519 } Sa_SWInfo_t;
1522 /**
1523 * @ingroup salld_api_macros
1524 * @brief sa_SWINFO_UPDATE_DEST_INFO is used to update the destination information within swInfo[2] at @ref Sa_SWInfo_t
1525 *
1526 * @note this macro is not applicable for socs such as AM65XX that have second generation SA Ultra Lite (SA2_UL)
1527 *
1528 * @details The application may want to deliver output packets to different queues for load balance.
1529 * This macro is used to update the destination queue and CPPI flow number in the Sa_SWInfo_t data structure
1530 * provided by Sa_chanSendData()
1531 *
1532 */
1533 #define sa_SWINFO_UPDATE_DEST_INFO(info, queueID, flowIndex) \
1534 { \
1535 (info[0]) |= 0x40000000L; \
1536 (info[2]) = ((queueID)) | (((flowIndex) & 0xFF) << 16) | ((info[2]) & 0xFF000000L); \
1537 } \
1539 /**
1540 * @ingroup salld_api_structures
1541 * @brief SA Command Label Parameter Information structure
1542 *
1543 * Data structure defines the updating information of parameters which may be updated within the
1544 * command label per packet.
1545 *
1546 */
1548 typedef struct {
1549 uint8_t index; /**< Specify the index of the starting 32-bit command word */
1550 uint8_t offset; /**< specify the offset to the parameter within the command word */
1551 uint8_t size; /**< Specify the size of parameter in bytes */
1553 } Sa_CmdLbParamInfo_t;
1555 /**
1556 * @defgroup DataSubModes Data Sub Operation Modes
1557 * @ingroup salld_api_constants
1558 * @{
1559 *
1560 * @name Data Sub Operation Modes
1561 *
1562 * Definition of the sub operation modes in Data mode.
1563 * Enhanced the sub modes to more general types of protocols such as WiMax.
1564 * Pleae refer to @ref Sa_DataModeConfigParams_t restrictions table
1565 * on supported IV, Salt and AAD sizes
1566 *
1567 */
1568 /*@{*/
1569 typedef enum {
1570 sa_DM_GEN = 0, /**< General operation mode */
1571 sa_DM_CCM, /**< CCM IPSEC */
1572 sa_DM_CCM_GEN, /**< CCM non IPSEC */
1573 sa_DM_GCM, /**< GCM IPSEC */
1574 sa_DM_GCM_GEN, /**< GCM non IPSEC */
1575 sa_DM_GMAC, /**< GMAC IPSec */
1576 sa_DM_GMAC_GEN, /**< GMAC non IPSec*/
1577 sa_DM_GMAC_AH /**< GMAC for IPSEC AH */
1578 } Sa_DM_subMode_e;
1579 /*@}*/
1580 /** @} */
1583 /**
1584 * @defgroup SALLDCmdLbUpdateVaildInfo SALLD Command Label Update Vaild Bit Definitions
1585 * @ingroup salld_api_constants
1586 * @{
1587 *
1588 * @name Command Label Update Valid Bit Definitions
1589 *
1590 * Bitmap definition of the validBitfield in Sa_CmdLbUpdateInfo_t.
1591 */
1592 /*@{*/
1593 /**
1594 * @def sa_CMDL_UPDATE_VALID_ENC
1595 * Control Info -- Encryption related information is valid
1596 */
1597 #define sa_CMDL_UPDATE_VALID_ENC 0x0001
1598 /**
1599 * @def sa_CMDL_UPDATE_VALID_AUTH
1600 * Control Info -- Authentication related information is valid
1601 */
1602 #define sa_CMDL_UPDATE_VALID_AUTH 0x0002
1603 /**
1604 * @def sa_CMDL_UPDATE_VALID_ENC_IV
1605 * Control Info -- Encryption IV is valid
1606 */
1607 #define sa_CMDL_UPDATE_VALID_ENC_IV 0x0004
1608 /**
1609 * @def sa_CMDL_UPDATE_VALID_AUTH_IV
1610 * Control Info -- Authentication IV valid
1611 */
1612 #define sa_CMDL_UPDATE_VALID_AUTH_IV 0x0008
1613 /**
1614 * @def sa_CMDL_UPDATE_VALID_AAD
1615 * Control Info -- AAD is valid
1616 */
1617 #define sa_CMDL_UPDATE_VALID_AAD 0x0010
1618 /**
1619 * @def sa_CMDL_UPDATE_VALID_AUX_KEY
1620 * Control Info -- CMAC-type Auxiliary key is valid
1621 */
1622 #define sa_CMDL_UPDATE_VALID_AUX_KEY 0x0020
1623 /**
1624 * @def sa_CMDL_UPDATE_VALID_PAYLOAD
1625 * Control Info -- Payload pending is valid such as GMAC mode
1626 */
1627 #define sa_CMDL_UPDATE_VALID_PAYLOAD 0x0040
1628 /**
1629 * @def sa_CMDL_UPDATE_VALID_ENC_SIZE
1630 * Control Info -- Second encryption size update is required, such as CCM mode
1631 */
1632 #define sa_CMDL_UPDATE_VALID_ENC_SIZE 0x0080
1633 /**
1634 * @def sa_CMDL_UPDATE_VALID_ENC_IV2
1635 * Control Info -- Second encryption IV update is required, such as CCM mode
1636 */
1637 #define sa_CMDL_UPDATE_VALID_ENC_IV2 0x0100
1638 /**
1639 * @def sa_CMDL_UPDATE_VALID_AUTH_SIZE
1640 * Control Info -- Second authentication size update is required, such as GMAC mode
1641 */
1642 #define sa_CMDL_UPDATE_VALID_AUTH_SIZE 0x0200
1644 /*@}*/
1645 /** @} */
1648 /**
1649 * @ingroup salld_api_structures
1650 * @brief SA Command Label Updating Information structure
1651 *
1652 * Data structure provides the information how to update the command label. The application can
1653 * use this information to update the command label per packet without invoking Sa_chanSendData() API.
1654 *
1655 */
1657 typedef struct {
1658 uint16_t validBitfield; /**< Specify the parameter valid Information as defined at @ref SALLDCmdLbUpdateVaildInfo */
1659 uint16_t subMode; /**< Specify the sub operation modes as defined at @ref DataSubModes */
1660 Sa_CmdLbParamInfo_t encSizeInfo; /**< Information used to update encryption size */
1661 Sa_CmdLbParamInfo_t encSizeInfo2; /**< Information used to update 2nd encryption size */
1662 Sa_CmdLbParamInfo_t encOffsetInfo; /**< Information used to update encryption offset */
1663 Sa_CmdLbParamInfo_t encIvInfo; /**< Information used to update encryption initialization vector */
1664 Sa_CmdLbParamInfo_t encIvInfo2; /**< Information used to update 2nd encryption initialization vector */
1665 Sa_CmdLbParamInfo_t aadInfo; /**< Information used to update AAD */
1666 Sa_CmdLbParamInfo_t payloadInfo; /**< Information used to update payload padding information */
1667 Sa_CmdLbParamInfo_t authSizeInfo; /**< Information used to update authentication size */
1668 Sa_CmdLbParamInfo_t authSizeInfo2; /**< Information used to update 2nd authentication size */
1669 Sa_CmdLbParamInfo_t authOffsetInfo; /**< Information used to update authentication offset */
1670 Sa_CmdLbParamInfo_t authIvInfo; /**< Information used to update authentication initialization vector */
1671 Sa_CmdLbParamInfo_t auxKeyInfo; /**< Information used to update auxiliary Key information */
1672 uint32_t auxKey[8]; /**< Contain auxiliary key1/key2 */
1673 } Sa_CmdLbUpdateInfo_t;
1675 /**
1676 * @ingroup salld_api_constants
1677 * @brief Define the maxmium size of the command label stored at cmdLbBuf of @ref Sa_CmdLabelInfo_t.
1678 */
1679 #define sa_MAX_CMDLB_SIZE 96
1681 /**
1682 * @ingroup salld_api_structures
1683 * @brief SA Command Label Information structure
1684 *
1685 * Data structure defines the SA-specific command label information used by SA to route packet
1686 * to sub-engines within SA. The command label information will be formatted by the SA LLD
1687 * based on the channel configuration parameters and the payload information as defined at
1688 * @ref Sa_PayloadInfo_t. The command label should be copied to the protocol-specific section
1689 * at the CPPI packet descriptor as provided through the CPPI LLD or equivalent component.
1690 *
1691 * @note: This structure is only used in Data Mode and the cmdLbBuf should be provided by the
1692 * caller.
1693 */
1694 typedef struct {
1695 uint16_t cmdLbSize; /**< Specify the command label size in bytes */
1696 uint8_t* cmdLbBuf; /**< Pointer to the buffer which contains the command labels
1697 The buffer should be allocated by the caller in Data
1698 Mode opeation and 4-byte alignment is required*/
1699 Sa_CmdLbUpdateInfo_t* cmdLbUpdateInfo; /**< Pointer to command label updating data structure, the command
1700 label updating information will be provided upon return if not
1701 NLL pointer */
1702 } Sa_CmdLabelInfo_t;
1704 /**
1705 * @ingroup salld_api_structures
1706 * @brief SA Payload Information structure
1707 *
1708 * Data structure providing the payload related information used to construct the
1709 * SA-specific command labels in data mode
1710 */
1711 typedef struct {
1712 uint8_t encOffset; /**< Specify the offset to the encrypted/decrypted data in the packet in bytes */
1713 uint8_t authOffset; /**< Specify the offset to the authenticated data in the packet in bytes */
1714 uint16_t encSize; /**< Specify the total number of bytes to be encrypted or decrypted */
1715 uint16_t authSize; /**< Specify the total number of bytes to be authenticated */
1716 uint8_t* encIV; /**< Contain the initialization vectors used in certain encryption modes.
1717 @note: IV should be specified here in GCM/GMAC/CCM mode */
1718 uint8_t* authIV; /**< Contain the initialization vectors used in certain authentication modes.*/
1719 uint8_t* aad; /**< Contain the additional authenticated data in GCM/GMAC/CCM modes */
1720 } Sa_PayloadInfo_t;
1722 /**
1723 * @ingroup salld_api_structures
1724 * @brief SA Rx Payload Information structure
1725 *
1726 * Data structure providing the miscellaneous header information of the received packets which is
1727 * required for the IPSEC post-processing function to patch the outer IP header when the inner IP
1728 * fragments have been reassembled by the hardware IP reassembly engine (RA) on the NSS Gen2 devices.
1729 *
1730 * @note: This structure should be provided at the Sa_chanReceiveData() call when the RA engine is enabled
1731 * for inner IP. If it is not provided, the IPSEC post-processing function will not be able to handle
1732 * inner IP reassembled packets correctly.
1733 */
1734 typedef struct {
1735 uint8_t ipOffset; /**< Specify the offset to the outer IP in the packet in bytes */
1736 uint8_t ipOffset2; /**< Specify the offset to the inner IP in the packet in bytes
1737 (0: indicates there is no inner IP) */
1738 } Sa_RxPayloadInfo_t;
1741 /**
1742 * @ingroup salld_api_structures
1743 * @brief SA IPSEC NAT-T structure
1744 *
1745 * Data structure defines the IPSEC NAT-T parameters used by @ref Sa_chanSendData() API to
1746 * construct the IPSEC NAT-T (UDP) header which resides in front of IPSEC ESP header.
1747 */
1748 typedef struct {
1749 uint16_t dstPort; /**< Specify the destination UDP port number */
1750 uint16_t srcPort; /**< Specify the source UDP port number */
1751 } Sa_ipsecNatTInfo_t;
1753 /**
1754 * @defgroup SALLDPktInfoValidBits SALLD Packet Info Valid Bit Definitions
1755 * @ingroup salld_api_constants
1756 * @{
1757 *
1758 * @name SALLD Packet Info Valid Bit Definitions
1759 *
1760 * Bitmap definition of the validBitMap in Sa_PktInfo_t.
1761 */
1762 /*@{*/
1763 /**
1764 * @def sa_PKT_INFO_VALID_PKT_ERR_CODE
1765 * - pktErrorCode is present
1766 */
1767 #define sa_PKT_INFO_VALID_PKT_ERR_CODE 0x0001
1768 /**
1769 * @def sa_PKT_INFO_VALID_SW_INFO
1770 * - swInfo is present
1771 */
1772 #define sa_PKT_INFO_VALID_SW_INFO 0x0002
1773 /**
1774 * @def sa_PKT_INFO_VALID_CMDLB_INFO
1775 * - cmdlb is present
1776 */
1777 #define sa_PKT_INFO_VALID_CMDLB_INFO 0x0004
1778 /**
1779 * @def sa_PKT_INFO_VALID_PAYLOAD_INFO
1780 * - payloadInfo is present
1781 */
1782 #define sa_PKT_INFO_VALID_PAYLOAD_INFO 0x0008
1783 /**
1784 * @def sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO
1785 * - natTInfo is present
1786 */
1787 #define sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO 0x0010
1788 /**
1789 * @def sa_PKT_INFO_VALID_RX_PAYLOAD_INFO
1790 * - rxPayloadInfo is present
1791 */
1792 #define sa_PKT_INFO_VALID_RX_PAYLOAD_INFO 0x0020
1795 /*@}*/
1796 /** @} */
1798 /**
1799 * @defgroup SALLDEspInfoTxRxValidBits SALLD ESP TxRx Info Valid Bit Definitions
1800 * @ingroup salld_api_constants
1801 * @{
1802 *
1803 * @name SALLD ESP TxRx Valid Bit Definitions
1804 *
1805 * Bitmap definition of the validBitMap in salldIpsecEspTxRxInfo_t.
1806 */
1807 /*@{*/
1808 /**
1809 * @def sa_ESP_TXRX_VALID_IPSEC_NAT_T_INFO
1810 * - espTxRx_natTInfo is present
1811 */
1812 #define sa_ESP_TXRX_VALID_IPSEC_NAT_T_INFO sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO
1813 /**
1814 * @def sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO
1815 * - rxPayloadInfo is present
1816 */
1817 #define sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO sa_PKT_INFO_VALID_RX_PAYLOAD_INFO
1819 /*@}*/
1820 /** @} */
1823 /**
1824 * @ingroup salld_api_structures
1825 * @brief IpSec ESP Data send/receive info structure
1826 *
1827 */
1828 typedef struct salldIpsecEspTxRxInfo_s {
1829 uint16_t validBitMap; /**< Specify which parameters are vaild as defined at @ref SALLDEspInfoTxRxValidBits */
1830 uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
1831 uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
1832 uint16_t encryptionBlockSize; /**< Specify the encryption block size
1833 1: Stream encryption and no alignment requirement
1834 4: AES-CTR or other stream-like encryption with 4-byte
1835 alignment
1836 block size: block encryption algorithm */
1837 Sa_ipsecNatTInfo_t natTInfo; /**< Specify the IPSEC NAT-T parameters, if natTInfo is present*/
1838 Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
1839 } salldIpsecEspTxRxInfo_t;
1841 /**
1842 * @ingroup salld_api_structures
1843 * @brief Packet Descriptor structure
1844 *
1845 * The packet may consist of one or more segments.
1846 * Several assumptions regarding the data organization among these segment(s) were made,
1847 * in compliance with requirements from the supported protocols. Below are a
1848 * list of assumptions imposed upon each packet with regard to their corresponding protocol.
1849 *
1850 * - IPSec
1851 * -# [Transmit] Segment containing IP Header must reserve approx 32 bytes of buffer space at the
1852 * beginning of the segment, to allow insertion of ESP/AH header after the IP header.
1853 * -# [Transmit] Final segment containing IP Datagram must reserve approx 32 bytes of buffer space at the
1854 * end of the segment, to allow insertion of ESP padding, ESP trailer and authentication tag.
1855 * -# [General] IP Header must be contiguous and in one segment.
1856 * - SRTP
1857 * -# [Transmit] Final segment containing SRTP payload must reserve approx 16 bytes of buffer space at the
1858 * end of the segment, to allow insertion of MKI and authentication tag.
1859 * -# [General] RTP Header must be contiguous in one segment.
1860 * -# [Receive] Total number of segments used to carry SRTP payload may not exceed 10.
1861 * - Air Cipher
1862 * -# No assumptions were made as data segments are untouched by the processing function.
1863 * - Data Mode
1864 * -# No assumptions were made as data segments are untouched by the processing function.
1865 *
1866 * @note Elements in the packet descriptor structure may change, after each protocol specific processing.
1867 */
1868 typedef struct {
1869 int32_t size; /**< packet length */
1870 uint16_t payloadOffset; /**< offset from base of the packet to the header
1871 of protocol per the following list:
1872 IPSEC ESP/AH: IP header
1873 IPSEC ESP(Output): ESP Header
1874 SRTP: RTP header
1875 SRTCP: RTCP header
1876 3GPP Air Ciphering: PDU header */
1877 uint16_t payloadLen; /**< length of the payload starting from payloadOffset to the end of the protocol */
1878 uint16_t nSegments; /**< number of segments */
1879 void** segments; /**< data segments */
1880 uint16_t *segUsedSizes; /**< pointer to segment used size array */
1881 uint16_t *segAllocSizes; /**< pointer to segment allocated size array */
1882 } Sa_PktDesc_t; /* base class */
1884 /**
1885 * @ingroup salld_api_structures
1886 * @brief Packet Information structure
1887 *
1888 * Data structure defines the SALLD input/output packet formats
1889 *
1890 */
1891 typedef struct {
1892 Sa_PktDesc_t pktDesc; /**< Specify packet descriptor */
1893 uint16_t validBitMap; /**< Specify which parameters are vaild as defined at @ref SALLDPktInfoValidBits */
1894 uint16_t pktErrCode; /**< Specify the error code of the received packet as defined at Sa_PktErr_t */
1895 Sa_SWInfo_t swInfo; /**< Specify the software information required by SA */
1896 Sa_CmdLabelInfo_t cmdlb; /**< Specify the command label in data mode */
1897 Sa_PayloadInfo_t payloadInfo;/**< Specify the payload information in data mode */
1898 Sa_ipsecNatTInfo_t natTInfo; /**< Specify the IPSEC NAT-T parameters */
1899 Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
1900 } Sa_PktInfo_t;
1902 /**
1903 * @defgroup SALLDSrtpKeyReqInfo SALLD SRTP Key Request Info Control Bit Definitions
1904 * @ingroup salld_api_constants
1905 * @{
1906 *
1907 * @name SRTP Key Request Info Control Bit Definitions
1908 *
1909 * Bitmap definition of the ctrlBitfield in Sa_SrtpKeyRequest_t.
1910 */
1911 /*@{*/
1912 /**
1913 * @def sa_SRTP_KEY_REQUEST_KEY_TYPE_MKI
1914 * Control Info -- Set: MKI Key
1915 * Clear: From-To Key
1916 */
1917 #define sa_SRTP_KEY_REQUEST_KEY_TYPE_MKI 0x0001
1918 /**
1919 * @def sa_SRTP_KEY_REQUEST_TX_KEY
1920 * Control Info -- Request Tx key
1921 */
1922 #define sa_SRTP_KEY_REQUEST_TX_KEY 0x0002
1923 /**
1924 * @def sa_SRTP_KEY_REQUEST_RX_KEY
1925 * Control Info -- Request Rx key
1926 */
1927 #define sa_SRTP_KEY_REQUEST_RX_KEY 0x0004
1928 /**
1929 * @def sa_SRTP_KEY_REQUEST_MKI_VALID
1930 * Control Info -- MKI VALUE included
1931 */
1932 #define sa_SRTP_KEY_REQUEST_MKI_VALID 0x0008
1934 /*@}*/
1935 /** @} */
1937 /**
1938 * @ingroup salld_api_structures
1939 * @brief SRTP Key Request structure
1940 *
1941 * Data structure defines the key request information for SRTP
1942 *
1943 */
1944 typedef struct {
1945 uint16_t ctrlBitfield; /**< Specify the Key types and other control Information
1946 as defined at @ref SALLDSrtpKeyReqInfo */
1947 uint32_t mki; /**< Specify the MKI value of the MKI keys */
1948 } Sa_SrtpKeyRequest_t;
1950 /**
1951 * @ingroup salld_api_structures
1952 * @brief Key Request structure
1953 *
1954 * Data structure defines the key request information for all supported protocols
1955 *
1956 */
1957 typedef struct {
1958 union {
1959 Sa_SrtpKeyRequest_t srtp; /**< Specify the key request parameters for SRTP */
1960 } params; /**< Contain the protocol-specific key request information */
1961 } Sa_KeyRequest_t;
1963 /**
1964 * @ingroup salld_api_structures
1965 * @brief Security Context Request Information structure
1966 *
1967 * SASS is equipped with context cache module to auto-fetch security context
1968 * from external memory. This module is essential to allow any number of simultaneous
1969 * security connections by caching only limited (64) contexts on-chip and fetching other
1970 * contexts as and when required for processing.
1971 *
1972 * In order to facilitate fast retrieval for performance critical connections such as IPSEC channels,
1973 * context cache module allows two tier of security connections. First tier has permanent
1974 * residence within Context cache RAM for fast retrieval and is never evicted automatically
1975 * by context cache module. Second tier connections are kept as long as space is available within
1976 * context cache RAM; new fetch request may automatically evict the context of the second tier connections
1977 * into external memory to allow free space.
1978 *
1979 * The following data structure defines the parameters for the security context request.
1980 * The 15-bit security context ID, of which LSB 4-bits act as cache set select, and
1981 * its corresponding context buffer, which contains the protocol-specific security parameters
1982 * used by the LLD and sub-engines within SA, should be maintained across multiple DSP cores.
1983 * They are multi-core resources and should be managed by the application.
1984 *
1985 * The security context IDs and buffers can be managed across mult-cores or be pre-allocated for
1986 * each core or each security channel. The security context buffer should be 16-byte aligned at least
1987 * and it should be cache-line aligned if it is allocated at cacheable memory. It is recommended to
1988 * maintain the security context buffers in the following three lists:
1989 *
1990 * @verbatim
1991 Allocated: The buffer and its corresponding ID have been allocated to the SA
1992 LLD through *ScAlloc API and they are owned by SA.
1993 Pending Free: The buffer and its corresponding ID has been released from the
1994 SA LLD through *ScFree API. However, they are still owned by
1995 SA until the security context tear-down procedure is complete.
1996 The API Sa_isScBufFree should be used to check
1997 whether the buffer is free
1998 Free: The buffer and its corresonding ID are owned by the application.
1999 @endverbatim
2000 *
2001 * @note There are only up to three first tier contexts allowed for each cache set.
2002 *
2003 * @note It is highly recommended to place the security context buffers at non-cacheable memory
2004 * since they are accessed and maintained by the SA sub-system primarily
2005 *
2006 * @note The application can manage the security context buffers and IDs as
2007 * two seperate resources or a single resource pair. The only
2008 * requirement is that the security context ID cannot be re-used until
2009 * its corresponding security context buffer is free.
2010 * The application may perform periodic checks to move buffers from the
2011 * Pending Free list to the Free list or perform checks only when new
2012 * buffers are requested by the SA LLD.
2013 */
2014 typedef struct {
2015 uint16_t scSize; /**< Specify the size of the required security context */
2016 uint16_t scID; /**< Security Context ID specified by the application */
2017 uintptr_t scBuf; /**< Security Context Buffer provided by the application
2018 (16-byte alignment required) */
2019 } Sa_ScReqInfo_t;
2021 /**
2022 * @def sa_SC_ID_MASK
2023 * Define security context ID mask.
2024 */
2025 #define sa_SC_ID_MASK 0x7FFF
2027 /**
2028 * @def sa_SC_IND_PERMANENT
2029 * Indicate that the corresponding security context is permanent
2030 */
2031 #define sa_SC_IND_PERMANENT 0x8000
2034 /**
2035 * @defgroup saScMaxSize Security Context maximum size requirements
2036 * @ingroup salld_api_constants
2037 * @{
2038 *
2039 * @name Security Context maximum size
2040 *
2041 * Define Security Context maximum size requirements.
2042 */
2043 /* @{ */
2045 /**
2046 * @def sa_IPSEC_TX_MAX_SC_SIZE
2047 * The maximum security context size required for IPSEC Tx channel
2048 */
2049 #define sa_IPSEC_TX_MAX_SC_SIZE 288
2052 /**
2053 * @def sa_IPSEC_RX_MAX_SC_SIZE
2054 * The maximum security context size required for IPSEC Rx channel
2055 *
2056 * Note: The maxmium IPSEC Rx channel security context includes the extra 128 bytes used by
2057 * large replay window when the replay window size exceeds 128.
2058 */
2059 #define sa_IPSEC_RX_MAX_SC_SIZE 448
2060 #define sa_IPSEC_RX_MAX_SC_SIZE_SM_REPLAY_WINDOW 320
2062 /**
2063 * @def sa_SRTP_TX_MAX_SC_SIZE
2064 * The maximum security context size required for SRTP Tx channel
2065 */
2066 #define sa_SRTP_TX_MAX_SC_SIZE 224
2069 /**
2070 * @def sa_SRTP_RX_MAX_SC_SIZE
2071 * The maximum security context size required for SRTP Rx channel
2072 */
2073 #define sa_SRTP_RX_MAX_SC_SIZE 288
2075 /**
2076 * @def sa_AC_MAX_SC_SIZE
2077 * The maximum security context size required for Air Ciphering channel
2078 */
2079 #define sa_AC_MAX_SC_SIZE 288
2081 /**
2082 * @def sa_DATA_MODE_MAX_SC_SIZE
2083 * The maximum security context size required for Data Mode channel
2084 */
2085 #define sa_DATA_MODE_MAX_SC_SIZE 256
2087 /**
2088 * @def sa_MAX_SC_SIZE
2089 * Define the maxmium size of the security context buffer defined at @ref Sa_ScReqInfo_t.
2090 */
2091 #define sa_MAX_SC_SIZE 448
2093 /* @} */
2094 /** @} */
2096 /**
2097 * @ingroup salld_api_constants
2098 * @brief Define the maxmium replay window size supported by SASS.
2099 */
2100 #define sa_MAX_REPLAY_WINDOW_SIZE 1024
2101 #define sa_MAX_REPLAY_WINDOW_SIZE_GEN1 128 /* first generation SASS */
2102 #define sa_MAX_REPLAY_WINDOW_SIZE_GEN2 1024 /* second generation SASS */
2104 /**
2105 * @ingroup salld_api_structures
2106 * @brief SALLD Replay Window Context
2107 *
2108 * This structure defines the replay window context which reprenets the snapshot of
2109 * SASS replay windows.
2110 */
2112 typedef struct Sa_Replay_Cxt_tag
2113 {
2114 uint32_t winMask[sa_MAX_REPLAY_WINDOW_SIZE/32]; /**< Bitmask Array:w0.b0, w0.b1, ... w1.b0, w0.b2 ...
2115 1:packet received
2116 0:packet not received*/
2117 uint32_t winBaseHi; /**< Upper 32-bit of win_base when ESN is enabled */
2118 uint32_t winBase; /**< Lower 32-bit of win_base which represents the sequence number of
2119 the oldest packet received */
2120 } Sa_Replay_Cxt_t;
2122 /**
2123 * @defgroup SALLDStatsCtrlBit SALLD Statistics Query Control Bit Definitions
2124 * @ingroup salld_api_constants
2125 * @{
2126 *
2127 * @name SALLD Statistics Query Control Bit Definitions
2128 * Bitmap definition of the control flags in Sa_chanGetStats() API.
2129 */
2130 /*@{*/
2131 /**
2132 * @def sa_STATS_QUERY_FLAG_CLEAR
2133 * Control Info -- Clear some statistics after they are reported
2134 */
2135 #define sa_STATS_QUERY_FLAG_CLEAR 0x0001
2136 /**
2137 * @def sa_STATS_QUERY_FLAG_TRIG
2138 * Control Info -- Inform the SA Sub-system to provide statistics
2139 */
2140 #define sa_STATS_QUERY_FLAG_TRIG 0x0002
2141 /**
2142 * @def sa_STATS_QUERY_FLAG_NOW
2143 * Control Info -- Request the SA LLD to provide the latest available statistics
2144 * If the bit is not set, the SA LLD will return sa_ERR_STATS_UNAVAIL if the
2145 * latest statistics is not available
2146 */
2147 #define sa_STATS_QUERY_FLAG_NOW 0x0004
2148 /*@}*/
2149 /** @} */
2151 /**
2152 * @ingroup salld_api_structures
2153 * @brief SALLD SRTP Statistics Structure
2154 *
2155 * This structure defines the SRTP-specific statistics provided upon request
2156 * with salldChanStats().
2157 */
2158 typedef struct {
2159 uint32_t replayOld; /**< Number of replay failures with old packets */
2160 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2161 uint32_t authFail; /**< Number of Authentication failures */
2162 uint32_t txROC; /**< Tx Roll-over Counter (32-bits) */
2163 uint32_t rxROC; /**< RX Roll-Over Counter (32 bits) */
2164 uint16_t txRekey; /**< Number of times re-keying happened in Tx */
2165 uint16_t rxRekey; /**< Number of times re-keying happened in Rx */
2166 uint16_t pktEncHi; /**< Total Number of Packets encrypted with this key (48-bits) Upper 16 bits */
2167 uint32_t pktEncLo; /**< Total Number of Packets encrypted with this key (48-bits) Lower 32 bits */
2168 uint16_t pktDecHi; /**< Total Number of Packets decrypted with this key (48-bits) Upper 16 bits */
2169 uint32_t pktDecLo; /**< Total Number of Packets decrypted with this key (48-bits) Lower 32 bits */
2170 } Sa_SrtpStats_t;
2172 /**
2173 * @ingroup salld_api_structures
2174 * @brief SALLD SRTCP Statistics Structure
2175 *
2176 * This structure defines the SRTCP-specific statistics provided upon request
2177 * with salldChanStats().
2178 */
2179 typedef struct {
2180 uint32_t replayOld; /**< Number of replay failures with old packets */
2181 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2182 uint32_t authFail; /**< Number of Authentication failures */
2183 uint16_t txRekey; /**< Number of times re-keying happened in Tx */
2184 uint16_t rxRekey; /**< Number of times re-keying happened in Rx */
2185 uint32_t pktEnc; /**< Total Number of Packets encrypted with this key (32-bits) */
2186 uint32_t pktDec; /**< Total Number of Packets decrypted with this key (32-bits) */
2187 } Sa_SrtcpStats_t;
2189 /**
2190 * @ingroup salld_api_structures
2191 * @brief SALLD IPSEC Statistics Structure
2192 *
2193 * This structure defines the IPSEC-specific statistics provided upon request
2194 * with salldChanStats().
2195 */
2196 typedef struct {
2197 Sa_Replay_Cxt_t replayCxt; /**< Snapshot of the replay context */
2198 uint32_t replayOld; /**< Number of replay failures with old packets */
2199 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2200 uint32_t authFail; /**< Number of Authentication failures */
2201 uint32_t txRollover; /**< Number of Tx packets dropped due to rollover error, i.e. the sequence number exceed its limit (0xFFFFFFFF) */
2202 uint32_t txESN; /**< Tx ESN (32-bits) */
2203 uint32_t txSN; /**< Sequence Number (32-bits) of the last transmitted packet */
2204 uint32_t rxESN; /**< RX ESN (32 bits) */
2205 uint32_t pktEncHi; /**< Total Number of Packets encrypted with this key (64-bits) Upper 32 bits */
2206 uint32_t pktEncLo; /**< Total Number of Packets encrypted with this key (64-bits) Lower 32 bits */
2207 uint32_t pktDecHi; /**< Total Number of Packets decrypted with this key (64-bits) Upper 32 bits */
2208 uint32_t pktDecLo; /**< Total Number of Packets decrypted with this key (64-bits) Lower 32 bits */
2209 uint32_t txByteCountHi; /**< Total bytes processed by SA on TX (64-bits) Upper 32 bits */
2210 uint32_t txByteCountLo; /**< Total bytes processed by SA on TX (64-bits) Lower 32 bits */
2211 uint32_t rxByteCountHi; /**< Total bytes processed by SA on RX (64-bits) Upper 32 bits */
2212 uint32_t rxByteCountLo; /**< Total bytes processed by SA on RX (64-bits) Lower 32 bits */
2213 } Sa_IpsecStats_t;
2215 /**
2216 * @ingroup salld_api_structures
2217 * @brief SALLD Air Ciphering Statistics Structure
2218 *
2219 * This structure defines the Air Ciphering-specific statistics provided upon request
2220 * with salldChanStats().
2221 */
2222 typedef struct {
2223 uint32_t authFail; /**< Number of Authentication failures */
2224 uint32_t toAirCountC; /**< To-Air Count-C (32-bits) */
2225 uint32_t fromAirCountC; /**< From-Air Count-C (32-bits) */
2226 uint32_t pktToAirHi; /**< Total Number of To-Air Packets (64-bits) Upper 32 bits */
2227 uint32_t pktToAirLo; /**< Total Number of To-Air Packets (64-bits) Lower 32 bits */
2228 uint32_t pktFromAirHi; /**< Total Number of From-Air Packets (64-bits) Upper 32 bits */
2229 uint32_t pktFromAirLo; /**< Total Number of From-Air Packets (64-bits) Lower 32 bits */
2230 } Sa_AcStats_t;
2232 /**
2233 * @ingroup salld_api_structures
2234 * @brief SALLD Data Mode Statistics Structure
2235 *
2236 * This structure defines the Data Mode statistics provided upon request
2237 * with salldChanStats().
2238 */
2239 typedef struct {
2240 uint32_t pktHi; /**< Total Number of processed Packets (64-bits) Upper 32 bits */
2241 uint32_t pktLo; /**< Total Number of processed Packets (64-bits) Lower 32 bits */
2242 } Sa_DataModeStats_t;
2244 /**
2245 * @ingroup salld_api_structures
2246 * @brief SALLD Statistics Structure
2247 *
2248 * This structure defines the protocol-specific statistics provided upon request
2249 * with salld_chanGetStats().
2250 */
2251 typedef union {
2252 Sa_SrtpStats_t srtp; /**< SRTP-specific channel statistics */
2253 Sa_SrtcpStats_t srtcp; /**< SRTCP-specific channel statistics */
2254 Sa_IpsecStats_t ipsec; /**< IPSEC-specific channel statistics */
2255 Sa_AcStats_t ac; /**< 3GPP Air Ciphering-specific channel statistics */
2256 Sa_DataModeStats_t data; /**< Data Mode channel statistics */
2257 } Sa_Stats_t;
2259 /**
2260 * @ingroup salld_api_structures
2261 * @brief Specification of Sa_Handle
2262 * The Sa_Handle is used to identify a SALLD system instance
2263 */
2264 typedef void* Sa_Handle;
2266 /**
2267 * @defgroup saConfigCtrlBit SA Configuration Control Bit Definitions
2268 * @ingroup salld_api_constants
2269 * @{
2270 *
2271 * @name SA Configuration Control Bit Definitions
2272 *
2273 * Bitmap definition of the ctrlBitMap in Sa_Config_t.
2274 *
2275 */
2276 /*@{*/
2277 /**
2278 * @def sa_CONFIG_CTRL_BITMAP_TRIGGER_SYS_ERR_HALT
2279 * Control Info -- 0:Disable trigger PDSP halt during system errors (refer to @ref appendix3)
2280 * 1:Enables trigger PDSP halt during system errors (for Debug Purpose only).
2281 */
2283 #define sa_CONFIG_CTRL_BITMAP_TRIGGER_SYS_ERR_HALT 0x0001
2285 /**
2286 * @def sa_CONFIG_CTRL_BITMAP_TRIGGER_PKT_INFO_LOG
2287 * Control Info -- 0:Disable internal internal packet information data collection (refer to @ref appendix3)
2288 * 1:Enables internal internal packet information data collection (for Debug Purpose only)
2289 *
2290 * @note This control bit is applicable to Air Cipher channels only. This fetaure should not be enabled if there might be
2291 * both Air Cipher and SRTP channels. This feature bit is not supported for C6678 device.
2292 */
2294 #define sa_CONFIG_CTRL_BITMAP_TRIGGER_PKT_INFO_LOG 0x0002
2296 /**
2297 * @def sa_CONFIG_CTRL_BITMAP_SET_SCPTR_RANGE
2298 * Control Info -- 0:Disable setting of security context pointer range limit set
2299 * 1:Enables security context pointer range limit set
2300 *
2301 * @note This control bit is applicable to SA2UL only (for other generations it is don't care).
2302 * For SA2UL promote (packet from non secure to secure operations), the security context range needs to be
2303 * set in SCPTR_Promote_Range registers
2304 */
2306 #define sa_CONFIG_CTRL_BITMAP_SET_SCPTR_RANGE 0x0004
2310 /*@}*/
2311 /** @} */
2313 /**
2314 * @ingroup salld_api_structures
2315 * @brief The SALLD Call-out function table
2316 *
2317 * The SALLD software module requires a set of call-out functions to report debug information,
2318 * request and free system resources, and etc. All the call-out functions should be implemented
2319 * by the application and provided to the SALLD at @ref Sa_create
2320 *
2321 */
2322 typedef struct Sa_CallOutFuns_s {
2324 /**
2325 * @brief A callout to the system code's debug and exception handling function. This is a function
2326 * pointer and must point to a valid function which meets the API requirements.
2327 *
2328 * @param[in] handle SALLD channel instance identifier.
2329 * @param[in] msgType Specify how serious the debug message is as defined at @ref salldDebugMessageTypes.
2330 * @param[in] msgCode Specify the message code as defined at @ref salldDebugMessageCodes.
2331 * @param[in] msgLength Specify the length of the message supporting data.
2332 * @param[in] msgData Pointer to the message supporting data.
2333 */
2334 void (*DebugTrace) (Sa_ChanHandle handle, uint16_t msgType, uint16_t msgCode,
2335 uint16_t msgLength, uint16_t *msgData);
2336 /**
2337 * @brief Callout to externally supplied system to request a new security key. This function may be triggered
2338 * by either the Sa_chanSendData() or Sa_chanReceiveData() APIs. The application should call the
2339 * Sa_chanControl() API to pass the new key when it is available.
2340 * This is a function pointer and must point to a valid function which meets the API requirements.
2341 *
2342 * @param[in] handle SALLD channel instance identifier.
2343 * @param[in] keyReq Pointer to SALLD key Request structure.
2344 *
2345 * @sa Sa_KeyRequest_t
2346 *
2347 */
2348 void (*ChanKeyRequest) (Sa_ChanHandle handle, Sa_KeyRequest_t* keyReq);
2350 /**
2351 * @brief Callout to externally supplied system to allocate the security context with the specified size.
2352 * This function must be implemented as a simple non-blocking function.
2353 * This is a function pointer and must point to a valid function which meets the API requirements.
2354 *
2355 * @param[in] handle SALLD channel instance identifier.
2356 * @param[in] scReqInfo Pointer to SALLD security context Request Information structure.
2357 *
2358 * @sa Sa_ScReqInfo_t
2359 *
2360 * @note:Both the base address and size of the security context buffer should be cache-line and csche-line size
2361 * aligned if it is allocated at cacheable memory, otherwise, the base address should be 16-byte aligned.
2362 * It is highly recommended to place the security context buffers at non-cacheable memory
2363 * since they are accessed and maintained by the SA sub-system primarily
2364 */
2365 void (*ScAlloc) (Sa_ChanHandle handle, Sa_ScReqInfo_t* scReqInfo);
2367 /**
2368 * @brief Callout to externally supplied system to release the security context with the specified ID.
2369 * This function must be implemented as a simple non-blocking function.
2370 * This is a function pointer and must point to a valid function which meets the API requirements.
2371 *
2372 * @param[in] handle SALLD channel instance identifier.
2373 * @param[in] scID Security Context ID
2374 *
2375 * @note The security context buffer is only released from the SA LLD and is still owned by SA.
2376 * It should be maintained at the Pending Free list until it is freed by SA.
2377 * Use API @ref Sa_isScBufFree() to check its status.
2378 *
2379 */
2380 void (*ScFree) (Sa_ChanHandle handle, uint16_t scID);
2382 /**
2383 * @brief Callout to externally supplied system to register the security channel with its software
2384 * routing information to be programmed into the PASS lookup table in the from-Network direction.
2385 * It may be triggered by the Sa_chanControl(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2386 * This is a function pointer and must point to a valid function which meets the API requirements.
2387 *
2388 * @param[in] handle SALLD channel instance identifier.
2389 * @param[in] chanSwInfo Pointer to SALLD software routing information structure.
2390 *
2391 * @sa Sa_SWInfo_t
2392 *
2393 */
2394 void (*ChanRegister) (Sa_ChanHandle handle, Sa_SWInfo_t* chanSwInfo);
2396 /**
2397 * @brief Callout to externally supplied system to un-register the security channel with its software
2398 * routing information to be removed from the PASS lookup tables. It may be triggered by
2399 * the sSa_chanClose(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2400 * This is a function pointer and must point to a valid function which meets the API requirements.
2401 *
2402 * @param[in] handle SALLD channel instance identifier.
2403 * @param[in] chanSwInfo Pointer to SALLD software routing information structure.
2404 *
2405 * @sa Sa_SWInfo_t
2406 *
2407 */
2408 void (*ChanUnRegister) (Sa_ChanHandle handle, Sa_SWInfo_t* chanSwInfo);
2410 /**
2411 * @brief Callout to externally supplied system to send an Null packet to the SA sub-system.
2412 * The null packet is used to evict and/or tear down the security context associated with the channel.
2413 * It may be triggered by the Sa_chanClose(), Sa_chanSendData() and Sa_chanReceiveData() APIs.
2414 * This is a function pointer and must point to a valid function which meets the API requirements.
2415 *
2416 * @param[in] handle SALLD channel instance identifier.
2417 * @param[in] pktInfo Pointer to the packet info structure.
2418 *
2419 * @sa Sa_PktInfo_t
2420 *
2421 */
2422 void (*ChanSendNullPkt) (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo);
2424 } Sa_CallOutFuncs_t;
2426 /**
2427 * @ingroup salld_api_structures
2428 * @brief SA Size Configuration Structure
2429 *
2430 * @details The module is configured at run time with a maximum number of channels supported.
2431 */
2432 typedef struct {
2433 uint16_t nMaxChan; /**< Maximum number of channels supported */
2434 int cacheLineSize; /**< Specify the size of cache line of the memory where the system buffer will reside
2435 @note cacheLineSize should be the larger of cache line sizes amoung mixed processors */
2436 uint16_t ctrlBitMap; /**< Various configuration information as specified at @ref saSizeConfigCtrlBit */
2437 } Sa_SizeCfg_t;
2439 /**
2440 * @ingroup salld_api_structures
2441 * @brief SA Security Context Range Structure for promote operations
2442 *
2443 * @details for SA2UL promote operations, the range register needs to be set with correct address ranges
2444 */
2445 typedef struct {
2446 uint32_t scPtrPromoteLowRangeL; /**< The lower 32-bits of SCPTR lower limit (must be 4KB aligned) */
2447 uint32_t scPtrPromoteLowRangeH; /**< The upper 16-bits of SCPTR lower limit */
2448 uint32_t scPtrPromoteHighRangeL; /**< The lower 32-bits of SCPTR upper limit (must be 4KB aligned) */
2449 uint32_t scPtrPromoteHighRangeH; /**< The upper 16-bits of SCPTR upper limit */
2450 } Sa_ScPtrRangeCfg_t;
2452 /**
2453 * @defgroup saEngSelMode SA Engine Selector Algorithms
2454 * @ingroup salld_api_constants
2455 * @{
2456 *
2457 * @name SA Engine Selector Algorithms
2458 *
2459 * There are two sets of IPSEC processing engines at the second generation SASS.
2460 * During SA initialization, user may configure IPSEC processing engine set
2461 * selection algorithm to be used during channel creation by setting the variable
2462 * engSelMode to the following values:
2463 *
2464 * - 0 (Load balanced)
2465 * -# SA will select the set of engines with lower channel utility
2466 * - 1 (Channel-based Round Robin selection)
2467 * -# SA will use each set of engines interleaved in order for each channel created
2468 * - 2 (User Select)
2469 * -# User will specify engine set to use when creating new channel
2470 */
2471 /*@{*/
2473 typedef enum {
2474 sa_EngSelMode_LOADBALANCED = 0,
2475 sa_EngSelMode_ROUNDROBIN,
2476 sa_EngSelMode_USERSPECIFIED
2477 } Sa_EngSelMode_e;
2478 /*@}*/
2479 /** @} */
2481 /**
2482 * @ingroup salld_api_structures
2483 * @brief SALLD Configuration structure
2484 *
2485 * Data structure providing configuration information in @ref Sa_create()
2486 *
2487 */
2488 typedef struct {
2489 uint32_t ID; /**< User specified module ID */
2490 uint32_t baseAddr; /**< Specify the SASS base address */
2491 Sa_CallOutFuncs_t *callTable; /**< Pointer to call-out function Table */
2492 Sa_EngSelMode_e engSelMode; /**< User specified authentication/encryption
2493 engine set selection mode */
2494 void* intBuf; /**< Pointer to an arbitrary internal buffer of at least @ref sa_MAX_SC_SIZE bytes
2495 for temporary key storage during air ciphering security
2496 context construction, The buffer needs an alignment of 4 bytes */
2497 Sa_SizeCfg_t *sizeConfig; /**< SALLD memory allocation requirement structure */
2498 void *instPoolBaseAddr; /**< Base address of the global shared memory pool from which global
2499 LLD instance & channel instance memory is allocated.*/
2500 void *scPoolBaseAddr; /**< Base address of the global shared memory pool from which SA
2501 security context memory is allocated. This is a DMA\92able memory */
2502 Sa_ScPtrRangeCfg_t scPtrRange; /**< Security Context Buffer Range low and high address configuration */
2503 uint32_t ctrlBitMap; /**< Various configuration information as specified at @ref saConfigCtrlBit */
2504 } Sa_Config_t;
2506 /**
2507 * @ingroup salld_api_structures
2508 * @brief SALLD SRTP System Statistics Structure
2509 *
2510 * This structure defines the SRTP-specific system statistics provided upon request
2511 * with Sa_getSysStats().
2512 */
2513 typedef struct {
2514 uint32_t replayOld; /**< Number of replay failures with old packets */
2515 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2516 uint32_t authFail; /**< Number of Authentication failures */
2517 uint32_t pktEncHi; /**< Total Number of Packets encrypted Upper 32 bits */
2518 uint32_t pktEncLo; /**< Total Number of Packets encrypted Lower 32 bits */
2519 uint32_t pktDecHi; /**< Total Number of Packets decrypted Upper 32 bits */
2520 uint32_t pktDecLo; /**< Total Number of Packets decrypted Lower 32 bits */
2521 } Sa_SrtpSysStats_t;
2523 /**
2524 * @ingroup salld_api_structures
2525 * @brief SALLD IPSEC System Statistics Structure
2526 *
2527 * This structure defines the IPSEC-specific system statistics provided upon request
2528 * with Sa_getSysStats().
2529 */
2530 typedef struct {
2531 uint32_t replayOld; /**< Number of replay failures with old packets */
2532 uint32_t replayDup; /**< Number of replay failures with duplicated packets */
2533 uint32_t authFail; /**< Number of Authentication failures */
2534 uint32_t pktEncHi; /**< Total Number of Packets encrypted Upper 32 bits */
2535 uint32_t pktEncLo; /**< Total Number of Packets encrypted Lower 32 bits */
2536 uint32_t pktDecHi; /**< Total Number of Packets decrypted Upper 32 bits */
2537 uint32_t pktDecLo; /**< Total Number of Packets decrypted Lower 32 bits */
2538 } Sa_IpsecSysStats_t;
2540 /**
2541 * @ingroup salld_api_structures
2542 * @brief SALLD Air Ciphering System Statistics Structure
2543 *
2544 * This structure defines the Air Ciphering-specific systrem statistics provided upon request
2545 * with Sa_getSysStats().
2546 */
2547 typedef struct {
2548 uint32_t authFail; /**< Number of Authentication failures */
2549 uint32_t pktToAirHi; /**< Total Number of To-Air Packets Upper 32 bits */
2550 uint32_t pktToAirLo; /**< Total Number of To-Air Packets Lower 32 bits */
2551 uint32_t pktFromAirHi; /**< Total Number of From-Air Packets Upper 32 bits */
2552 uint32_t pktFromAirLo; /**< Total Number of From-Air Packets Lower 32 bits */
2553 } Sa_AcSysStats_t;
2555 /**
2556 * @ingroup salld_api_structures
2557 * @brief SALLD Error System Statistics Structure
2558 *
2559 * This structure defines the SA error system statistics provided upon request
2560 * with Sa_getSysStats().
2561 */
2562 typedef struct {
2563 uint32_t errNoMem; /**< Number of packets dropped due to lack of PDSP instance memory */
2564 uint32_t errCtx; /**< Number of packets dropped due to security context error */
2565 uint32_t errEngine; /**< Number of packets dropped due to SA processing engine error */
2566 uint32_t errProto; /**< Number of packets dropped due to protocol error such as inavlid IP version */
2567 } Sa_ErrorSysStats_t;
2569 /**
2570 * @ingroup salld_api_structures
2571 * @brief SALLD Statistics Structure
2572 *
2573 * This structure defines the system statistics provided upon request
2574 * with @ref Sa_getSysStats().
2575 */
2576 typedef struct Sa_SysStats_s {
2577 Sa_ErrorSysStats_t err; /**< System Error statistics */
2578 Sa_IpsecSysStats_t esp; /**< IPSEC(ESP)-specific system statistics */
2579 Sa_IpsecSysStats_t ah; /**< IPSEC(AH)-specific system statistics */
2580 Sa_SrtpSysStats_t srtp; /**< SRTP-specific system statistics */
2581 Sa_AcSysStats_t ac; /**< 3GPP Air Ciphering-specific system statistics */
2582 } Sa_SysStats_t;
2584 /**
2585 * @defgroup PkaOpTypes PKA Arithmetic Operation Types
2586 * @ingroup salld_api_constants
2587 * @{
2588 *
2589 * @name PKA Arithmetic Operation Types
2590 *
2591 * Definition of PKA Arithmetic Operation Types
2592 * Parameter operation of @ref Sa_PkaReqInfo_t and @ref Sa_PkaReqInfo2_t should be set
2593 * to one of these types.
2594 */
2595 /*@{*/
2596 typedef enum {
2597 /**
2598 * List of PKA basic operations supported by both NSS PKA Gen1 and Gen2 devices.
2599 */
2600 sa_PKA_OP_ADD = 0, /**< Large Vector Addition (A+B)*/
2601 sa_PKA_OP_SUB, /**< Large Vector Subtraction (A-B)*/
2602 sa_PKA_OP_MUL, /**< Large Vector Mutiplication (A*B)*/
2603 sa_PKA_OP_DIV, /**< Large Vector Division (A/B)*/
2604 sa_PKA_OP_RSHIFT, /**< Large Vector Shift Right (A>>shiftval) */
2605 sa_PKA_OP_LSHIFT, /**< Large Vector Shift Left (A<<shiftval)*/
2606 sa_PKA_OP_COMP, /**< Large Vector Comparison (A?B)*/
2607 sa_PKA_OP_COPY, /**< Large Vector Copy (A->C)*/
2608 sa_PKA_OP_EXP2, /**< Large Vector Exponentiation (Cexp(A)mod(B))(2-bit ACT) (NSS PKA Gen1 only) */
2609 sa_PKA_OP_EXP4, /**< Large Vector Exponentiation (Cexp(A)mod(B))(4-bit ACT) (NSS PKA Gen1 only) */
2610 sa_PKA_OP_ADD_SUB, /**< Large Vector Addition plus Substraction (A+C-B) (NSS PKA Gen2 only) */
2611 sa_PKA_OP_MOD, /**< Large Vector Modulo (A%B) (NSS PKA Gen2 only) */
2612 /**
2613 * List of PKA complex operations supported by NSS PKA Gen2 devices only.
2614 */
2615 sa_PKA_OP_MODEXP, /**< Large Vector Modular Exponentiation: M**E(mod N) */
2616 sa_PKA_OP_MODEXP_CRT, /**< Large Vector Modular Exponentiation: CRT CRTpq(Mp**Dp (mod p), Mq**Dq (mod q), qInv) */
2617 sa_PKA_OP_MODINVp, /**< Large Vector Modular Inversion (prime): (1/Z) (mod N) */
2618 sa_PKA_OP_MODINV2m, /**< Large Vector Modular Inversion (binary): (1/Z) (mod N) */
2619 sa_PKA_OP_ECp_ADD, /**< Large Vector Point Add on a Prime Field Curve:
2620 * P1_xyx + P2_xyx ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) */
2621 sa_PKA_OP_ECp_MUL, /**< Large Vector Point Multiply on a Prime Field Curve:
2622 * k*P1_xyx ==> P0_xyz with P1_z = 1, on prime curve y**2=x**3+ax+b (mod p) */
2623 sa_PKA_OP_ECp_SCALE, /**< Large Vector Point Scale on a Prime Field Curve:
2624 * P1_xyx ==> P0_xyz with P0_z = 1, on prime curve y**2=x**3+ax+b (mod p) */
2625 sa_PKA_OP_ECp_MUL_SACLE, /**< Large Vector Point Multiply following by Scale on a Prime Field Curve:
2626 * k*P1_xyx ==> P0_xyz with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p) */
2627 sa_PKA_OP_EC2m_ADD, /**< Large Vector Point Add on a Binary Field Curve:
2628 * P1_xyx + P2_xyx ==> P0_xyz, on binary curve y**2=x**3 + ax + b (mod p) */
2629 sa_PKA_OP_EC2m_MUL, /**< Large Vector Point Multiply on a Binary Field Curve:
2630 * k*P1_xyx ==> P0_xyz with P1_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
2631 sa_PKA_OP_EC2m_SCALE, /**< Large Vector Point Scale on a Binary Field Curve:
2632 * P1_xyx ==> P0_xyz with P0_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
2633 sa_PKA_OP_EC2m_MUL_SACLE, /**< Large Vector Point Multiply following by Scale on a Binary Field Curve:
2634 * k*P1_xyx ==> P0_xyz with P1_z = 1 and P0_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
2635 sa_PKA_OP_ECp_DSA_SIGN, /**< Large Vector ECDSA sign operation on a Prime Field Curve:
2636 * k*P1_xyx ==> P0_xyz with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p)
2637 * r = P0x mod N, s = 1/k * (h + rd) mod N where h = hash(m)n, d = private key
2638 */
2639 sa_PKA_OP_ECp_DSA_VERIFY /**< Large Vector ECDSA verify operation on a Prime Field Curve:
2640 * u1*P1_xyx + u2 * Y ==> P0_xyz with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p)
2641 * u1 = h * w(mod N) and u2 = r * w mod N where where w = 1/s * mod N, h = hash(m)n, Y = public key
2642 */
2643 } Sa_PkaOpTypes_t;
2644 /*@}*/
2645 /** @} */
2647 /**
2648 * @defgroup PkaOpStatusCodes PKA Complex Operation Status Codes
2649 * @ingroup salld_api_constants
2650 * @{
2651 *
2652 * @name PKA Complex Operation Status Codes
2653 *
2654 * Status codes returned by PKA module for complex operation.
2655 */
2656 /*@{*/
2657 /**
2658 * @def sa_PKA_OP_STATUS_SUCCESS
2659 * PKA Complex Operation executed successfully
2660 */
2661 #define sa_PKA_OP_STATUS_SUCCESS 0x01
2662 /**
2663 * @def sa_PKA_OP_STATUS_PARAM_EVEN
2664 * Error: Modulus or Prime polynomial is even
2665 */
2666 #define sa_PKA_OP_STATUS_PARAM_EVEN 0x03
2667 /**
2668 * @def sa_PKA_OP_STATUS_PARAM_ZERO
2669 * Error: Exponent or Multiplier k is zero
2670 */
2671 #define sa_PKA_OP_STATUS_PARAM_ZERO 0x05
2672 /**
2673 * @def sa_PKA_OP_STATUS_PARAM_SHORT
2674 * Error: Modulus is too short
2675 */
2676 #define sa_PKA_OP_STATUS_PARAM_SHORT 0x07
2677 /**
2678 * @def sa_PKA_OP_STATUS_PARAM_ONE
2679 * Error: Exponent or Multiplier k is one
2680 */
2681 #define sa_PKA_OP_STATUS_PARAM_ONE 0x09
2682 /**
2683 * @def sa_PKA_OP_STATUS_INFINITY
2684 * Result is "at-infinity" (Z=0, not an error if
2685 * the scalar 'k' was the curve's order)
2686 */
2687 #define sa_PKA_OP_STATUS_INFINITY 0x0D
2688 /**
2689 * @def sa_PKA_OP_STATUS_ERR_INFINITY
2690 * Error: An intermediate result of ECpMUL was "at-infinity"
2691 */
2692 #define sa_PKA_OP_STATUS_ERR_INFINITY 0x0F
2693 /**
2694 * @def sa_PKA_OP_STATUS_NO_INVERSE
2695 * Error: No inverse exist
2696 */
2697 #define sa_PKA_OP_STATUS_NO_INVERSE 0x17
2699 /*@}*/
2700 /** @} */
2703 /**
2704 * @defgroup PkaCompResults PKA Comparison Results
2705 * @ingroup salld_api_constants
2706 * @{
2707 *
2708 * @name PKA Comparison Results
2709 *
2710 * Definition of PKA Comparsion Result from SALLD API @ref Sa_pkaOperation
2711 */
2712 /*@{*/
2713 typedef enum {
2714 sa_PKA_COMP_AEQB = 1, /**< A=B */
2715 sa_PKA_COMP_AINFB = 2, /**< A<B */
2716 sa_PKA_COMP_ASUPB = 4 /**< A>B */
2717 } Sa_PkaCompResults_t;
2718 /*@}*/
2719 /** @} */
2721 /*
2722 * @ingroup salld_api_constants
2723 * @brief Define the maxmium sizes of the PKA operands in 32-bit words.
2724 */
2725 #define sa_MAX_PKA_OPERAND_SIZE_GEN1 128 /**< General Operations 4k-bits or 128 32-bit words */
2726 #define sa_MAX_PKA_OPERAND_SIZE_EXP4 64 /**< EXP4 operation: 2k-bits or 64 32-bit words */
2728 #define sa_MAX_PKA_OPERAND_SIZE_GEN2 130 /**< General operations 4160 bits or 130 32-bit words */
2729 #define sa_MAX_PKA_OPERAND_SIZE_ECp 24 /**< Prime Curve related operations: 24 32-bit words */
2730 #define sa_MAX_PKA_OPERAND_SIZE_EC2m 18 /**< Binary Curve related operations:18 32-bit words */
2732 #ifdef NSS_PKA_GEN2
2733 #define sa_MAX_PKA_OPERAND_SIZE sa_MAX_PKA_OPERAND_SIZE_GEN2
2734 #else
2735 #define sa_MAX_PKA_OPERAND_SIZE sa_MAX_PKA_OPERAND_SIZE_GEN1
2736 #endif
2738 /**
2739 * @ingroup salld_api_structures
2740 * @brief SALLD PKA Operation Request Structure
2741 *
2742 * This structure defines PKA request information which is used to perform the large
2743 * vector arithmetic operations.
2744 *
2745 * @par
2746 *
2747 * Restrictions of input parameters:
2748 * - Add: 0 < Alength, Blength <= Max Len (128)
2749 * - Subtract:0 < Alength, Blength <= Max Len (128); Aoperand >= Boperand
2750 * - Multiply: 0 < Alength, Blength <= Max Len (128)
2751 * - Divide:
2752 * - Alength, Blength > 1
2753 * - Alength >= Blength
2754 * - Most significant word of Boperand can not be zero
2755 * - Right/Left Shift: 0 < Alength <= Max Len (128)
2756 * - Compare: 0 < Alength, Blength <= Max Len (128); Alength = Blength
2757 * - Copy: 0 < Alength <= Max Len (128)
2758 * - Exponentitation (2-bit/4-bit ACT):
2759 * - Alength > 0
2760 * - Blength > 1
2761 * - Blength >= Alength
2762 * - Aoperand cannot be zero
2763 * - Coperand cannot be zero
2764 * - Boperand is odd (least significant bit set to 1)
2765 * - Most significant word of Boperand can not be zero
2766 * - Boperand > Coperand
2767 */
2768 typedef struct {
2769 Sa_PkaOpTypes_t operation; /**< Specify the arithmetic operation as defined at salldPkaOpTypes_t */
2770 Sa_PkaCompResults_t cmpResult; /**< Store the comparsion result */
2771 uint16_t numShiftBits; /**< Specify number of bits in shift operation */
2772 uint16_t oprandSize[2]; /**< Specify the size of operands (A, B(C))in 32-bit words */
2773 uint16_t resultSize; /**< Specify the size of result in 32-bit words */
2774 uint16_t remSize; /**< Specify the size of reminder in 32-bit words */
2775 uint32_t* oprandPtr[3]; /**< Pointers to up to 3 operand (A,B and C) buffers*/
2776 uint32_t* remPtr; /**< Pointer to the buffer to store the reminder */
2777 uint32_t* resultPtr; /**< Pointer to the buffer to store the operation result */
2778 } Sa_PkaReqInfo_t;
2780 /**
2781 * @ingroup salld_api_structures
2782 * @brief SALLD PKA Basic Operation Parameters Structure
2783 *
2784 * This structure defines the input and output parameters for PKA basic operations
2785 *
2786 * @par
2787 *
2788 * Restrictions of input parameters:
2789 * - Add: 0 < ALen, BLen <= Max Len (130)
2790 * - Subtract: 0 < ALen, BLen <= Max Len (130); A >= B
2791 * - AddSub: 0 < ALen <= Max Len (130); (A+C) >= B; A, B, C all use ALen and BLen is ignored.
2792 * - Multiply: 0 < ALen, BLen <= Max Len (130)
2793 * - Divide and Modulo:
2794 * - ALen, BLen > 1
2795 * - ALen >= BLen
2796 * - Most significant 32-bit word of B operand cannot be zero
2797 * - Right/Left Shift: 0 < ALen <= Max Len (130)
2798 * - Compare: 0 < ALen <= Max Len (130); Both A and B use ALen and BLen is ignored.
2799 * - Copy: 0 < ALen <= Max Len (130)
2800 */
2801 typedef struct {
2802 uint32_t* pA; /**< Pointers to Aoperand in 32-bit word array */
2803 uint32_t* pB; /**< Pointers to Boperand in 32-bit word array */
2804 uint32_t* pC; /**< Pointers to Coperand in 32-bit word array */
2805 uint32_t numShiftBits; /**< Specify number of bits in shift operation */
2806 uint32_t* pRem; /**< Pointer to the 32-bit word buffer to store the reminder */
2807 uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
2808 uint16_t resultSize; /**< Store the size of operation result in 32-bit words */
2809 uint16_t remSize; /**< Store the size of reminder in 32-bit words of Divide/Modulo operations*/
2810 Sa_PkaCompResults_t cmpResult; /**< Store the comparison result */
2811 } Sa_PkaBasicOpParams_t;
2813 /**
2814 * @ingroup salld_api_structures
2815 * @brief SALLD PKA Modular Exponentiation Operation Parameters Structure
2816 *
2817 * This structure defines the input and output parameters of PKA Modular Exponentiation operation as
2818 * described with the following formula:
2819 *
2820 * M**E(mod N) ==> R
2821 *
2822 * E: ALen
2823 * M, N, R: BLen
2824 *
2825 * @par
2826 *
2827 * Restrictions of input parameters:
2828 * - 0 < ALen <= Max Len (130)
2829 * - 1 < BLen <= Max Len (130)
2830 * - Modulus N must be odd (i.e. the least significant bit must be ONE)
2831 * - Modulus N > 2**32
2832 * - Base M < Modulus N
2833 * - Number of pre-calculated odd powers to use >= 1
2834 *
2835 */
2836 typedef struct {
2837 uint32_t* pE; /**< Pointer to Exponent in 32-bit word array */
2838 uint32_t* pN; /**< Pointer to Modulus N in 32-bit word array */
2839 uint32_t* pM; /**< Pointer to Message (Base) M in 32-bit word array */
2840 uint32_t numOddPowers; /**< Specify number of pre-calculated odd powers to use */
2841 uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
2842 } Sa_PkaModExpParams_t;
2844 /**
2845 * @ingroup salld_api_structures
2846 * @brief SALLD PKA Modular Exponentiation CRT Operation Parameters Structure
2847 *
2848 * This structure defines the input and output parameters of PKA Modular Exponentiation CRT operation as
2849 * described with the following formula:
2850 *
2851 * CRTpq(Mp**Dp mod p, Mq**Dq mod q, qInv) ==> R
2852 *
2853 * where Mp = M mod p, Mq = M mod q and CRTpq(a, b, qInv) = ((a-b)*qInv mod p)*q + b
2854 *
2855 * Dp, Dq: ALen
2856 * p, q, qInv: BLen
2857 * M, R: 2*Blen
2858 *
2859 * @par
2860 *
2861 * Restrictions of input parameters:
2862 * - 0 < ALen <= Max Len (130)
2863 * - 1 < BLen <= Max Len (130)
2864 * - Modulus p and Modulus q must be odd (i.e. the least significant bit must be ONE)
2865 * - Modulus p > Modulus q > 2**32
2866 * - Modulus p and Modulus q must be co-prime (GCD(p,q) = 1)
2867 * - TBD: 0 < Exp P < (Mod P - 1)
2868 * - TBD: 0 < Exp Q < (Mod Q - 1)
2869 * - (qInv * q) = 1 (mod p)
2870 * - Base M < p*q
2871 * - Number of pre-calculated odd powers to use >= 1
2872 *
2873 */
2874 typedef struct {
2875 uint32_t* pDp; /**< Pointer to Exponent mod p in 32-bit word array */
2876 uint32_t* pDq; /**< Pointer to Exponent mod q in 32-bit word array */
2877 uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
2878 uint32_t* pModQ; /**< Pointer to Modulus q in 32-bit word array */
2879 uint32_t* pQInv; /**< Pointer to Modulus qInv in 32-bit word array */
2880 uint32_t* pM; /**< Pointer to Message (Base) M in 32-bit word array */
2881 uint32_t numOddPowers; /**< Specify number of pre-calculated odd powers to use */
2882 uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
2883 } Sa_PkaModExpCRTParams_t;
2885 /**
2886 * @ingroup salld_api_structures
2887 * @brief SALLD PKA Modular Inversion Operation Parameters Structure
2888 *
2889 * This structure defines the input and output parameters of PKA Modular Inversion operation as
2890 * described with the following formula:
2891 *
2892 * 1/Z (mod N) ==> R
2893 *
2894 * Z: ALen
2895 * N, R: BLen
2896 *
2897 * @par
2898 *
2899 * Restrictions of input parameters:
2900 * - ModINVp: 0 < ALen <= Max Len (130)
2901 * - ModINVp: 0 < BLen <= Max Len (130)
2902 * - ModINV2m: 0 < ALen <= 18
2903 * - ModINV2m: 0 < BLen <= 18
2904 * - ModINV2m: Z < Modulus N
2905 * - Modulus N must be odd (i.e. the least significant bit must be ONE)
2906 * - Modulus N should not be 1
2907 * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
2908 *
2909 */
2910 typedef struct {
2911 uint32_t* pN; /**< Pointer to Modulus N in 32-bit word array */
2912 uint32_t* pZ; /**< Pointer to operand Z in 32-bit word array */
2913 uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
2914 } Sa_PkaModInvParams_t;
2916 /**
2917 * @ingroup salld_api_structures
2918 * @brief SALLD PKA Field Curve Point Structure
2919 *
2920 * This structure specifies a point in projective format (X, Y, Z) on the Prime or Binary Field Curve used by
2921 * ECp or EC2m related operations
2922 *
2923 * Where the EC (Elliptic Curve) is represented as y**2=x**3 + ax + b (mod p) and
2924 * point in affine format (x,y) = (X/Z, Y/Z).
2925 *
2926 */
2927 typedef struct {
2928 uint32_t* pX; /**< Pointer to X in 32-bit word array */
2929 uint32_t* pY; /**< Pointer to Y in 32-bit word array */
2930 uint32_t* pZ; /**< Pointer to Z in 32-bit word array */
2931 } Sa_PkaECPoint_t;
2933 /**
2934 * @ingroup salld_api_structures
2935 * @brief SALLD PKA Elliptic Curve (EC) Point Add Operation Parameters Structure
2936 *
2937 * This structure defines the input and output parameters of Point Add operation on a
2938 * Prime (Binary) Field Curve as described below
2939 *
2940 * P1_xyz + P2_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or
2941 * binary curve y**2+xy=x**3+ax**2+b (mod p)
2942 *
2943 * ALen: not used
2944 * p, a, b, P1_x, P1_y, P1_z, P2_x, P2_y, P2_z, P0_x, P0_y, P0_z: BLen
2945 *
2946 * @par
2947 *
2948 * Restrictions of input parameters:
2949 * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
2950 * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
2951 * - Binary Curve: Modulus p must be a prime
2952 * - Prime Curve: Modulus p must be a prime > 2**63
2953 * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
2954 * - a < p and b < p
2955 * - P1 and P2 must be on the curve
2956 */
2957 typedef struct {
2958 uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
2959 uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
2960 uint32_t* pEcB; /**< Pointer to EC curve parameter b in 32-bit word array */
2961 Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
2962 Sa_PkaECPoint_t point2; /**< Pointers to input point 2 (P2_xyz) */
2963 Sa_PkaECPoint_t point0; /**< Pointers to output point 0 (P0_xyz) */
2964 } Sa_PkaECAddParams_t;
2966 /**
2967 * @ingroup salld_api_structures
2968 * @brief SALLD PKA Elliptic Curve (EC) Point Multiply Operation Parameters Structure
2969 *
2970 * This structure defines the input and output parameters of Point Multiply operation on a
2971 * Prime (Binary) Field Curve as described below
2972 *
2973 * k*P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P1_z = 1
2974 * binary curve y**2+xy=x**3+ax**2+b (mod p)
2975 * k: Alen
2976 * p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
2977 *
2978 * c**2 = b (md p) on the binary curve
2979 *
2980 * @par
2981 *
2982 * Restrictions of input parameters:
2983 * - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
2984 * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
2985 * - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
2986 * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
2987 * - Binary Curve: Modulus p must be a prime
2988 * - Prime Curve: Modulus p must be a prime > 2**63
2989 * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
2990 * - a < p and b < p
2991 * - P1 must be on the curve
2992 * - 1 < k <= n, where n is the curve's order.
2993 */
2994 typedef struct {
2995 uint32_t* pK; /**< Pointer to parameter k in 32-bit word array */
2996 uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
2997 uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
2998 uint32_t* pEcBC; /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
2999 Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
3000 Sa_PkaECPoint_t point0; /**< Pointers to output point 0 (P0_xyz) */
3001 } Sa_PkaECMulParams_t;
3003 /**
3004 * @ingroup salld_api_structures
3005 * @brief SALLD PKA Elliptic Curve (EC) Point Scale Operation Parameters Structure
3006 *
3007 * This structure defines the input and output parameters of Point Scale operation on a
3008 * Prime (Binary) Field Curve as described below
3009 *
3010 * P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P0_z = 1
3011 * binary curve y**2+xy=x**3+ax**2+b (mod p)
3012 * Alen (not used)
3013 * p, a, b, P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
3014 *
3015 * @par
3016 *
3017 * Restrictions of input parameters:
3018 * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3019 * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3020 * - Binary Curve: Modulus p must be a prime
3021 * - Prime Curve: Modulus p must be a prime > 2**63
3022 * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3023 * - a < p and b < p
3024 * - P1 must be on the curve
3025 */
3026 typedef struct {
3027 uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
3028 uint32_t* pEcA; /**< Pointer to equation parameter a in 32-bit word array */
3029 uint32_t* pEcB; /**< Pointer to equation parameter b in 32-bit word array */
3030 Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
3031 Sa_PkaECPoint_t point0; /**< Pointers to output point 0 (P0_xyz) */
3032 } Sa_PkaECScaleParams_t;
3034 /**
3035 * @ingroup salld_api_structures
3036 * @brief SALLD PKA Elliptic Curve (EC) DSA Sign Operation Parameters Structure
3037 *
3038 * This structure defines the input and output parameters of DSA Sign operation on a
3039 * Prime (Binary) Field Curve as described below
3040 *
3041 * k*P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P1_z = 1
3042 * binary curve y**2+xy=x**3+ax**2+b (mod p)
3043 * k: Alen
3044 * p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
3045 *
3046 * c**2 = b (md p) on the binary curve
3047 *
3048 * N: multiplicative (integer) order of the point P1 means that n times P1 = O
3049 * h: messgae hash truncated to n bit Hash(m)n
3050 * d: private key
3051 *
3052 * Output:
3053 * r = P0x mod n;
3054 * s = (1/k)(h + dr) mod N
3055 *
3056 * @par
3057 *
3058 * Restrictions of input parameters:
3059 * - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
3060 * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3061 * - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
3062 * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3063 * - Binary Curve: Modulus p must be a prime
3064 * - Prime Curve: Modulus p must be a prime > 2**63
3065 * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3066 * - a < p and b < p
3067 * - P1 must be on the curve
3068 * - 1 < k <= n, where n is the curve's order.
3069 */
3070 typedef struct {
3071 uint32_t* pK; /**< Pointer to parameter k in 32-bit word array */
3072 uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
3073 uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
3074 uint32_t* pEcBC; /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
3075 uint32_t* pN; /**< Pointer to multiplicative (integer) order N in 32-bit word array */
3076 uint32_t* pH; /**< Pointer to hash data (h) in 32-bit word array */
3077 uint32_t* pD; /**< Pointer to private key (d) in 32-bit word array */
3078 Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
3079 uint32_t* pR; /**< Pointer to output parameter r in 32-bit word array */
3080 uint32_t* pS; /**< Pointer to output parameter s in 32-bit word array */
3081 } Sa_PkaECDSASignParams_t;
3083 /**
3084 * @ingroup salld_api_structures
3085 * @brief SALLD PKA Elliptic Curve (EC) DSA Verify Operation Parameters Structure
3086 *
3087 * This structure defines the input and output parameters of ECDSA Verify operation on a
3088 * Prime (Binary) Field Curve as described below
3089 *
3090 * k*P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P1_z = 1
3091 * binary curve y**2+xy=x**3+ax**2+b (mod p)
3092 * k: Alen
3093 * p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
3094 *
3095 * c**2 = b (md p) on the binary curve
3096 *
3097 * N: multiplicative (integer) order of the point P1 means that n times P1 = O
3098 * h: messgae hash truncated to n bit Hash(m)n
3099 * d: private key
3100 *
3101 * Output:
3102 * r = P0x mod n;
3103 * s = (1/k)(h + dr) mod N
3104 *
3105 * @par
3106 *
3107 * Restrictions of input parameters:
3108 * - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
3109 * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
3110 * - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
3111 * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
3112 * - Binary Curve: Modulus p must be a prime
3113 * - Prime Curve: Modulus p must be a prime > 2**63
3114 * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
3115 * - a < p and b < p
3116 * - P1 must be on the curve
3117 * - 1 < k <= n, where n is the curve's order.
3118 */
3119 typedef struct {
3120 uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
3121 uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
3122 uint32_t* pEcBC; /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
3123 uint32_t* pN; /**< Pointer to multiplicative (integer) order N in 32-bit word array */
3124 uint32_t* pH; /**< Pointer to hash data (h) in 32-bit word array */
3125 Sa_PkaECPoint_t pY; /**< Pointer to public key (y) in 32-bit word array */
3126 Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
3127 uint32_t* pR; /**< Pointer to signature parameter r in 32-bit word array */
3128 uint32_t* pS; /**< Pointer to signature parameter s in 32-bit word array */
3129 uint32_t* pRes; /**< Pointer to output parameter Result (res) in 32-bit word array */
3130 } Sa_PkaECDSAVerifyParams_t;
3132 /**
3133 * @defgroup PkaOpModes PKA Operation Modes
3134 * @ingroup salld_api_constants
3135 * @{
3136 *
3137 * @name PKA Operation Modes
3138 *
3139 * Definition of PKA Operation Modes
3140 * Parameter mode of @ref Sa_PkaReqInfo2_t should be set to one of these modes.
3141 */
3142 /*@{*/
3143 typedef enum {
3144 /**
3145 * The API Sa_pkaOperation2() operates in blocking mode. The API call will not return until all specified operations
3146 * are completed or some error occurs.
3147 */
3148 sa_PKA_MODE_WAIT = 0,
3150 /**
3151 * The API Sa_pkaOperation2() operates in non-blocking mode. The API call will return immediately when the first PKA
3152 * operation is triggered or some input error occurs. The application should invoke API @ref Sa_pkaPoll() periodically
3153 * until all specified PKA operations are completed or PKA error occurs.
3154 *
3155 */
3156 sa_PKA_MODE_POLL,
3158 /**
3159 * The API Sa_pkaOperation2 operates in non-blocking mode. The API call will return immediately when the first PKA
3160 * operation is triggered or some input error occurs. The application should invoke API @ref Sa_pkaPoll() when
3161 * PKA interrupt occurs until all specified PKA operations are completed or PKA error occurs.
3162 *
3163 */
3164 sa_PKA_MODE_INT
3166 } Sa_PkaOpModes_t;
3167 /*@}*/
3168 /** @} */
3170 /**
3171 * @ingroup salld_api_structures
3172 * @brief SALLD PKA Operation Request Structure for second generation PKA module
3173 *
3174 * This structure defines PKA request information which is used to perform the basic
3175 * and complex large vector arithmetic operations on the second generation PKA.
3176 *
3177 */
3178 typedef struct {
3179 Sa_PkaOpTypes_t operation; /**< Specify the arithmetic operation as defined at salldPkaOpTypes_t */
3180 Sa_PkaOpModes_t mode; /**< Specify the operation mode as defined at salldPkaOpModes_t */
3181 uint16_t aLen; /**< Specify the parameter ALen in 32-bit words */
3182 uint16_t bLen; /**< Specify the parameter BLen in 32-bit words */
3183 int statusCode; /**< Status code of the complex operation as defined at PkaOpStatusCodes */
3184 union {
3185 Sa_PkaBasicOpParams_t basicOp; /**< Specify the input/output parameters for all basic PKA operations */
3186 Sa_PkaModExpParams_t modExp; /**< Specify the input/output parameters for modular exponentitation operation */
3187 Sa_PkaModExpCRTParams_t modExpCRT; /**< Specify the input/output parameters for modular exponentitation CRT operation */
3188 Sa_PkaModInvParams_t modInv; /**< Specify the input/output parameters for modular inversion operation */
3189 Sa_PkaECAddParams_t ecAdd; /**< Specify the input/output parameters for EC point add operation */
3190 Sa_PkaECMulParams_t ecMul; /**< Specify the input/output parameters for EC point multiply operation */
3191 Sa_PkaECScaleParams_t ecScale; /**< Specify the input/output parameters for EC point scale operation */
3192 Sa_PkaECDSASignParams_t ecDSASign; /**< Specify the input/output parameters for ECDSA Sign operation */
3193 Sa_PkaECDSAVerifyParams_t ecDSAVerify; /**< Specify the input/output parameters for ECDSA Sign operation */
3194 } params; /**< Specify the operation specific input/output parameters */
3195 } Sa_PkaReqInfo2_t;
3197 /**
3198 * @defgroup SALLDRngConfigCtrlInfo SALLD RNG Configuration Control Info Bit Definitions
3199 * @ingroup salld_api_constants
3200 * @{
3201 *
3202 * @name RNG Configuration Control Info Bit Definitions
3203 *
3204 * Bitmap definition of the ctrlBitfield in @ref Sa_RngConfigParams_t.
3205 */
3206 /*@{*/
3207 /**
3208 * @def sa_RNG_CTRL_REINIT
3209 * Control Info -- Set: Force re-initialization
3210 * Clear: Perform initialization only if not actived
3211 */
3212 #define sa_RNG_CTRL_REINIT 0x0001
3213 /**
3214 * @def sa_RNG_CTRL_ENABLE_INT
3215 * Control Info -- Set: Interrupt mode
3216 * Clear: Poll mode
3217 */
3218 #define sa_RNG_CTRL_ENABLE_INT 0x0002
3219 /**
3220 * @def sa_RNG_CTRL_RESET
3221 * Control Info -- Set: RNG reset
3222 */
3223 #define sa_RNG_CTRL_RESET 0x0004
3225 /*@}*/
3228 /**
3229 * @defgroup SALLDRng2ConfigCtrlInfo SALLD RNG2 Configuration Control Info Bit Definitions
3230 * @ingroup salld_api_constants
3231 * @{
3232 *
3233 * @name RNG2 Configuration Control Info Bit Definitions
3234 *
3235 * Bitmap definition of the ctrlBitfield in @ref Sa_Rng2ConfigParams_t.
3236 */
3237 /*@{*/
3238 /**
3239 * @def sa_RNG2_CTRL_REINIT
3240 * Control Info -- Set: Force re-initialization
3241 * Clear: Perform initialization only if not actived
3242 */
3243 #define sa_RNG2_CTRL_REINIT 0x0001
3245 /**
3246 * @def sa_RNG_CTRL_RESET
3247 * Control Info -- Set: RNG2 reset
3248 */
3249 #define sa_RNG2_CTRL_RESET 0x0002
3251 /**
3252 * @def sa_RNG2_CTRL_DRBG_USE
3253 * Control Info -- Set: DRBG use for SA2UL
3254 * Clear: No DRBG for SA2UL
3255 */
3256 #define sa_RNG2_CTRL_DRBG_USE 0x0004
3258 /**
3259 * @def sa_RNG2_CTRL_DRBG_KNOWN_TESTS
3260 * Control Info -- Set: DRBG use for SA2UL
3261 * Clear: No DRBG for SA2UL
3262 */
3263 #define sa_RNG2_CTRL_DRBG_KNOWN_TESTS 0x0008
3266 /*@}*/
3268 /** @} */
3270 /**
3271 * @ingroup salld_api_structures
3272 * @brief SALLD RNG Configuration Structure
3273 *
3274 * Data structure defines the RNG configuration related parameters
3275 *
3276 */
3277 typedef struct {
3278 uint16_t ctrlBitfield; /**< Specify the initialization mode and other control information as defined
3279 at @ref SALLDRngConfigCtrlInfo */
3280 uint16_t clockDiv; /**< Specify the clock divider (1, 16) 0: default */
3281 uint32_t startupCycles; /**< Specify the number of clock cycles (2**8, 2**24) to start up
3282 the random number generator initially(0:default) */
3283 uint32_t minRefillCycles; /**< Specify the minimum number of clock cycles (2**6, 2**14) to generate
3284 the next random number (0:default) */
3285 uint32_t maxRefillCycles; /**< Specify the maximum number of clock cycles (2**8, 2**24) to generate
3286 the next random number (0:default) */
3287 } Sa_RngConfigParams_t;
3289 /**
3290 * @ingroup salld_api_structures
3291 * @brief SALLD RNG2 Configuration Structure
3292 *
3293 * Data structure defines the RNG2 configuration related parameters
3294 *
3295 */
3296 typedef struct {
3297 uint16_t ctrlBitfield; /**< Specify the initialization mode and other control information as defined
3298 at @ref SALLDRng2ConfigCtrlInfo */
3299 uint16_t clockDiv; /**< Specify the clock divider (1, 16) 0: default */
3300 uint32_t sampleCycles; /**< Sets the number of FRO samples that are XOR-ed together into one bit
3301 to be shifted into the main shift register.
3302 This value must be such that there is at least one bit of entropy (in total)
3303 in each 8 bits that are shifted.
3304 Note: Value 0 in this field selects 65536 FRO samples to be XOR-ed together */
3305 uint32_t pStringLen; /** < Personalization string length in 32-bit words (valid values 1 thorugh 12) */
3306 uint32_t pStringData[sa_MAX_PS_AI_WORD_COUNT]; /** < Personalization String and Additional Input for SP-800-90A
3307 AES-256 DRBG (valid when DRBG is enabled */
3309 } Sa_Rng2ConfigParams_t;
3311 /**
3312 * @ingroup salld_api_structures
3313 * @brief SALLD RNG Output Structure
3314 *
3315 * This structure defines the random number output provided upon request
3316 * with @ref Sa_getRandomNum().
3317 */
3318 typedef struct {
3319 uint32_t hi; /**< Upper 32 bits of the lower 64-bit Random Number output */
3320 uint32_t lo; /**< Lower 32 bits of the lower 64-bit Random Number output */
3321 } Sa_RngData_t;
3323 /**
3324 * @ingroup salld_api_structures
3325 * @brief SALLD RNG2 Output Structure
3326 *
3327 * This structure defines the random number output provided upon request
3328 * with @ref Sa_getRandomNum2().
3329 */
3330 typedef struct {
3331 uint32_t hihi; /**< Upper 32 bits of the higher 64-bit Random Number output */
3332 uint32_t hilo; /**< Lower 32 bits of the higher 64-bit Random Number output */
3333 uint32_t hi; /**< Upper 32 bits of the lower 64-bit Random Number output */
3334 uint32_t lo; /**< Lower 32 bits of the lower 64-bit Random Number output */
3335 } Sa_Rng2Data_t;
3338 /**
3339 * @ingroup salld_api_constants
3340 * @brief Define the maximum number of buffers the module (SALLD) can request
3341 *
3342 */
3343 #define sa_N_BUFS 1
3345 /**
3346 * @defgroup saBufIndex SA System Memory Buffer Index
3347 * @ingroup salld_api_constants
3348 * @{
3349 *
3350 * @name SA System Memory Buffer Index
3351 * @brief Define the buffer index of the SA system memory blocks.
3352 *
3353 */
3354 /* @{ */
3355 /**
3356 * @def sa_SYS_BUF_INST
3357 * SA LLD system instance buffer
3358 */
3359 #define sa_SYS_BUF_INST 0
3361 /* @} */
3362 /** @} */
3364 /** @name COMMON (Common Interface) APIs
3365 *
3366 */
3367 /*@{*/
3369 /**
3370 * @ingroup salld_api_functions
3371 * @brief Sa_getBufferReq returns the memory requirements for the SALLD instance.
3372 *
3373 * @details This function returns the memory buffer requirements in terms of the size and
3374 * alignment array. The SA LLD requires only one memory block as described below:
3375 * - SA Instance: SA instance data
3376 *
3377 * @param[in] sizeCfg Size configuration information
3378 * @param[out] sizes Array of size requirements
3379 * @param[out] aligns Array of alignment requirements
3380 * @retval Value @ref salldRetCodes
3381 *
3382 * @sa Sa_SizeCfg_t
3383 */
3384 int16_t Sa_getBufferReq (Sa_SizeCfg_t *sizeCfg, int sizes[], int aligns[]);
3386 /**
3387 * @ingroup salld_api_functions
3388 * @brief Sa_create creates the SA LLD instance. It initializes the SALLD instance
3389 * and its corresponding instance structure based on channel configuration data
3390 * such as the call-out table, and etc.
3391 *
3392 * @param[in] cfg Configuration information
3393 * @param[in] bases Array of the memory buffer base addresses
3394 * @param[out] pHandle Instance handle. This is a pointer to an initialized
3395 * instance structure.
3396 * @retval Value @ref salldRetCodes
3397 *
3398 * @sa Sa_Config_t
3399 *
3400 * @note The system buffers should be allocated from global accessible memory blocks and global
3401 * addresses should be used if the LLD instance is expected to be shared among multiple cores.
3402 *
3403 */
3404 int16_t Sa_create (Sa_Config_t *cfg, void* bases[], Sa_Handle *pHandle);
3406 /**
3407 * @ingroup salld_api_functions
3408 * @brief Sa_start activates the SA LLD instance
3409 *
3410 * @details This function activates the SA LLD instance. This function should
3411 * be called once at all other DSP cores which share the same SALLD
3412 * instance.
3413 *
3414 * @param[in] handle The PA LLD instance identifier
3415 * @param[in] cfg Configuration information
3416 * @retval Value @ref salldRetCodes
3417 *
3418 * @note: It is optional to call the function at the DSP core where Sa_create() is
3419 * invoked.
3420 */
3421 int16_t Sa_start (Sa_Handle handle, Sa_Config_t *cfg);
3423 /**
3424 * @ingroup salld_api_functions
3425 * @brief Sa_getShadowHandle queries the shadow system handle.
3426 *
3427 * @details This function returns the shadow system handle. The shadow system handle
3428 * is set to NULL if it does not exist. Refer to @ref appendix2 for details
3429 *
3430 * @param[in] handle The PA LLD instance identifier
3431 * @param[in] shandle Pointer to the shadow system handle
3432 * @retval Value @ref salldRetCodes
3433 *
3434 */
3435 int16_t Sa_getShadowHandle (Sa_Handle handle, Sa_Handle *shandle);
3438 /**
3439 * @ingroup salld_api_functions
3440 * @brief Sa_close deactivates the SA LLD instance
3441 *
3442 * @details This function deactivates the SA LLD instance, all the associated
3443 * memory buffers can be freed after this call.
3444 *
3445 * @param[in] handle The PA LLD instance identifier
3446 * @param[out] bases Array of the memory buffer base addresses
3447 * @retval Value @ref salldRetCodes
3448 */
3449 int16_t Sa_close (Sa_Handle handle, void* bases[]);
3451 /**
3452 * @ingroup salld_api_functions
3453 * @brief This function obtains SALLD system statistics.
3454 *
3455 * @param[in] handle SALLD instance identifier.
3456 * @param[in, out] stats pointer to system statistics
3457 * @retval Value @ref salldRetCodes
3458 */
3459 int16_t Sa_getSysStats (Sa_Handle handle, Sa_SysStats_t *stats);
3461 /**
3462 * @ingroup salld_api_functions
3463 * @brief This function controls the reset state of the SA Sub-System
3464 *
3465 * @details This function is used to assert or release reset for the sub-system. Asserting reset does not
3466 * reset any of the sub-system internal data, but only the packet processing modules. To acheive
3467 * a complete system reset the system-level reset must be asserted through the power controller.
3468 *
3469 * @param[in] handle SALLD instance identifier.
3470 * @param[in] newState Value @ref salldSubSysStates
3471 * @retval Value @ref salldSubSysStates
3472 * @pre None
3473 */
3474 Sa_State_t Sa_resetControl (Sa_Handle handle, Sa_State_t newState);
3476 /**
3477 * @ingroup salld_api_functions
3478 * @brief This function downloads a PDSP image to a PDSP core within the SA sub-system.
3479 *
3480 * @details This function is used to download an executable image to a packet processing module.
3481 *
3482 * @param[in] handle SALLD instance identifier.
3483 * @param[in] modId The PDSP number (0-1)
3484 * @param[in] image The image to download
3485 * @param[in] sizeBytes The size of the image
3486 * @retval Value @ref salldRetCodes
3487 * @pre The packet processing modules must be in reset. See @ref Sa_resetControl.
3488 */
3489 int16_t Sa_downloadImage (Sa_Handle handle, int modId, void* image, int sizeBytes);
3491 /**
3492 * @ingroup salld_api_functions
3493 * @brief The function is called to initialize and configure the RNG (Random Number Generator) module
3494 * inside SA
3495 *
3496 * @remark For a multi-core device, it is up to the upper-layer application to make sure that only
3497 * the master core performs the RNG hardware initialization.
3498 *
3499 * @param[in] handle SALLD instance identifier.
3500 * @param[in] cfg Pointer the RNG configuration parameters as defined at @ref Sa_RngConfigParams_t
3501 * @retval Value @ref salldRetCodes
3502 * @pre None
3503 */
3504 int16_t Sa_rngInit (Sa_Handle handle, Sa_RngConfigParams_t* cfg);
3506 /**
3507 * @ingroup salld_api_functions
3508 * @brief The function is called to initialize and configure the RNG (Random Number Generator) module
3509 * inside SA2UL
3510 *
3511 * @remark For a multi-core device, it is up to the upper-layer application to make sure that only
3512 * the master core performs the RNG hardware initialization.
3513 *
3514 * @param[in] handle SALLD instance identifier.
3515 * @param[in] cfg Pointer the RNG configuration parameters as defined at @ref Sa_RngConfigParams_t
3516 * @retval Value @ref salldRetCodes
3517 * @pre None
3518 */
3519 int16_t Sa_rng2Init (Sa_Handle handle, Sa_Rng2ConfigParams_t* cfg);
3522 /**
3523 * @ingroup salld_api_functions
3524 * @brief This function returns a 64-bit true random number
3525 *
3526 * @details This function is called to get a 64-bit true random number. It is a non-blocking function
3527 * call which indicates the random number is not available if the RNG is still in the
3528 * process of generating the next random number.
3529 * @remark For a multi-core device, it is up to the application to prevent this function from being invoked
3530 * by multiple CGEM cores simultaneously.
3531 *
3532 * @param[in] handle SALLD instance identifier.
3533 * @param[in] f_isr Flag to indicate whether it is called from interrupt srevice routine
3534 * @param[in] rnd Pointer to the 64-bit random number
3535 * @retval Value @ref salldRetCodes
3536 * @pre RNG is initialized
3537 */
3538 int16_t Sa_getRandomNum (Sa_Handle handle, uint16_t f_isr, Sa_RngData_t* rnd);
3540 /**
3541 * @ingroup salld_api_functions
3542 * @brief This function returns a 128-bit true random number
3543 *
3544 * @details This function is called to get a 64-bit true random number. It is a non-blocking function
3545 * call which indicates the random number is not available if the RNG is still in the
3546 * process of generating the next random number.
3547 * @remark For a multi-core device, it is up to the application to prevent this function from being invoked
3548 * by multiple CGEM cores simultaneously.
3549 *
3550 * @param[in] handle SALLD instance identifier.
3551 * @param[in] f_isr Flag to indicate whether it is called from interrupt srevice routine
3552 * @param[in] rnd Pointer to the 128-bit random number
3553 * @retval Value @ref salldRetCodes
3554 * @pre RNG is initialized
3555 */
3556 int16_t Sa_getRandomNum2 (Sa_Handle handle, uint16_t f_isr, Sa_Rng2Data_t* rnd);
3558 /**
3559 * @ingroup salld_api_functions
3560 * @brief Sa_rngClose decativates the SA RNG module
3561 *
3562 * @details This function deactivates the SA RNG module and clears LLD internal state.
3563 *
3564 * @param[in] handle The PA LLD instance identifier
3565 * @retval Value @ref salldRetCodes
3566 */
3567 int16_t Sa_rngClose (Sa_Handle handle);
3569 /**
3570 * @ingroup salld_api_functions
3571 * @brief Sa_rngClose decativates the SA RNG module
3572 *
3573 * @details This function deactivates the SA RNG module and clears LLD internal state.
3574 *
3575 * @param[in] handle The PA LLD instance identifier
3576 * @retval Value @ref salldRetCodes
3577 */
3578 int16_t Sa_rng2Close (Sa_Handle handle);
3581 /**
3582 * @ingroup salld_api_functions
3583 * @brief This function initializes the PKA (Public Key Accelerator) module inside SA
3584 *
3585 * @details The function is called to initialize the PKA module inside SA.
3586 * @remark For a multi-core device, it is up to the upper-layer application to make sure that only
3587 * the master core performs the PKA hardware initialization.
3588 *
3589 * @param[in] handle SALLD instance identifier.
3590 * @retval Value @ref salldRetCodes
3591 * @pre None
3592 */
3593 int16_t Sa_pkaInit (Sa_Handle handle);
3595 /**
3596 * @ingroup salld_api_functions
3597 * @brief This function downloads the PKA firmware image to the second generation PKA module.
3598 *
3599 * @details This function is used to download an executable firmware image to the second
3600 * generation PKA module, triggers the firmware to run and verify its operation.
3601 * The PKA firmware is required for PKA to perform complex operations such as
3602 * modular exponentiation and etc.
3603 *
3604 * @param[in] handle SALLD instance identifier.
3605 * @param[in] image The image to download
3606 * @param[in] sizeWords The size of the image in 32-bit words
3607 * @param[out] pVersion The pointer to PKA firmware reversion number
3608 * @retval Value @ref salldRetCodes
3609 * @pre The PKA module has been initialized through API @ref Sa_pkaInit.
3610 */
3611 int16_t Sa_pkaDownloadImage (Sa_Handle handle, void* image, int sizeWords, uint32_t* pVersion);
3613 /**
3614 * @ingroup salld_api_functions
3615 * @brief This function triggers a large vector arithmetic operation through the PKA module
3616 *
3617 * @details The function is called to perform a large vector arithmetic operation through the PKA module.
3618 * It is considered as a blocking function call since it will wait for the PKA module to complete
3619 * the arithmetic operation. However, it only takes a few cycles for PKA to complete any operation.
3620 * This function also returns with error code immediately if the PKA is still in the process to
3621 * perform the previous operation or when timeout occurs.
3622 * @remark For a multi-core device, it is up to the application to prevent this function from being invoked
3623 * by multiple CGEM cores simultaneously.
3624 * @note This API does not support the second generation PKA module
3625 *
3626 * @param[in] handle SALLD instance identifier.
3627 * @param[in] pkaReqInfo Pointer to the PKA operation request information structure
3628 * @retval Value @ref salldRetCodes
3629 * @pre PKA is initialized
3630 */
3631 int16_t Sa_pkaOperation (Sa_Handle handle, Sa_PkaReqInfo_t* pkaReqInfo);
3633 /**
3634 * @ingroup salld_api_functions
3635 * @brief This function triggers a large vector arithmetic operation through the PKA module
3636 *
3637 * @details Sa_pkaOperation2 is the next generation of PKA API to replace @ref Sa_pkaOperation eventually.
3638 * This new API supports both the first generation and second generation of PKA module.
3639 * The function is called to perform basic or complex large vector arithmetic operations through
3640 * the PKA module. It can operate in either blocking or non-blocking mode. In blocking mode, this API
3641 * will not return until the PKA module completes all requested large vector arithmetic operations.
3642 * In non-blocking mode, this API will returns immediately after it sets up and starts the first
3643 * requested PKA operation. And then the API @ref Sa_pkaPoll() should be invoked periodically or
3644 * per PKA interrupt until all PKA operations are completed and the final results are available.
3645 * This function also returns with error code immediately if the PKA is still in the process to
3646 * perform the previous operation or when timeout occurs.
3647 *
3648 * @note All simple operations should be done in blocking mode since it will only take a few cycles to
3649 * complete those operaion.
3650 *
3651 * @param[in] handle SALLD instance identifier.
3652 * @param[in] pPkaReqInfo Pointer to the PKA operation request information structure
3653 * @retval Value @ref salldRetCodes
3654 * @pre PKA is initialized. The complex operation will not work until the firmware image
3655 * is downloaded through API @ref Sa_pkaDownloadImage.
3656 */
3657 int16_t Sa_pkaOperation2 (Sa_Handle handle, Sa_PkaReqInfo2_t* pPkaReqInfo);
3659 /**
3660 * @ingroup salld_api_functions
3661 * @brief This function checks the status of the current large vector arithmetic operation and continue
3662 * the operation accordingly..
3663 *
3664 * @details Sa_pkaPoll is used to support non-blocking PKA operations. It should be called periodically
3665 * in Poll mode or per PKA interrupt in Interrupt mode. When it is invoked, this function checks
3666 * the status of the current PKA operation. If the operation is still in progress, it just
3667 * returns sa_PKA_OP_IN_PROGRESS. If the operation is complete and more operation is required,
3668 * it will prepare and trigger the next (complex) operation and then return sa_PKA_OP_CONTINUE,
3669 * otherwise, it copies operation results from the PKA registers and vector RAM to the result
3670 * locations specified by the PKA request information data structure and return sa_PKA_OP_COMPLETE.
3671 *
3672 * @param[in] handle SALLD instance identifier.
3673 * @param[out] pPkaReqInfo Pointer to the local copy of PKA operation request information structure
3674 * @retval Value @ref salldRetCodes
3675 * @pre PKA is initialized and Sa_pkaOperation2 has been invoked in non-block mode.
3676 */
3677 int16_t Sa_pkaPoll (Sa_Handle handle, Sa_PkaReqInfo2_t* pPkaReqInfo);
3679 /**
3680 * @ingroup salld_api_functions
3681 * @brief Sa_pkaClose decativates the SA PKA module
3682 *
3683 * @details This function deactivates the SA PKA module and clears LLD internal state.
3684 *
3685 * @param[in] handle The PA LLD instance identifier
3686 * @retval Value @ref salldRetCodes
3687 */
3688 int16_t Sa_pkaClose (Sa_Handle handle);
3690 /**
3691 * @ingroup salld_api_functions
3692 * @brief This function returns the SA system ID associated with the specified handle
3693 *
3694 * @details The function is called to request the SA system ID corresponding to the handle.
3695 *
3696 * @param[in] handle SALLD instance identifier.
3697 * @retval SA system ID
3698 * @pre Sa_create function should be called before calling this function
3699 */
3700 uint32_t Sa_getID (Sa_Handle handle);
3702 /**
3703 * @ingroup salld_api_functions
3704 * @brief Sa_getVersion returns the SA LLD version information
3705 *
3706 * @details This function is used to get the version information of the SA LLD in 0xAABBCCDD format.
3707 * where Arch (AA); API Changes (BB); Major (CC); Minor (DD)
3708 *
3709 * @retval 32-bit version information
3710 */
3711 uint32_t Sa_getVersion (void);
3714 /**
3715 * @ingroup salld_api_functions
3716 * @brief Sa_getVersionStr returns the SA LLD version string
3717 *
3718 * @details This function is used to get the version string of the SA LLD.
3719 *
3720 * @retval Version string
3721 */
3722 const char* Sa_getVersionStr (void);
3724 /**
3725 * @ingroup salld_api_functions
3726 * @brief Sa_getPDSPVersion returns the SA PDSP version information.
3727 *
3728 * @details This function is used to get the SA PDSP version information in 0xAABBCCDD format.
3729 * where Arch (AA); API Changes (BB); Major (CC); Minor (DD
3730 *
3731 * @param[in] handle SALLD instance identifier.
3732 * @param[in] modId The PDSP number (0-1)
3733 * @param[out] pVersion The pointer to PDSP version number
3734 * @retval Value @ref salldRetCodes
3735 * @pre The PDSP image should be downloaded successfully.
3736 *
3737 */
3738 int16_t Sa_getPDSPVersion (Sa_Handle handle, int modId, uint32_t *pVersion);
3740 /*@}*/ /* @name COMMON APIs */
3742 /**
3743 * @ingroup salld_api_constants
3744 * @brief Define the maximum number of buffers each SA LLD channel can request
3745 *
3746 */
3747 #define sa_CHAN_N_BUFS 1
3749 /**
3750 * @defgroup saChanBufIndex SA Channel Memory Buffer Index
3751 * @ingroup salld_api_constants
3752 * @{
3753 *
3754 * @name SA Channel Memory Buffer Index
3755 * @brief Define the buffer index of the SA channel memory blocks.
3756 *
3757 */
3758 /* @{ */
3759 /**
3760 * @def sa_CHAN_BUF_INST
3761 * SA LLD channel instance buffer
3762 */
3763 #define sa_CHAN_BUF_INST 0
3765 /* @} */
3766 /** @} */
3769 /** @name CHANNEL (Channel-Specific) APIs
3770 *
3771 */
3772 /*@{*/
3774 /**
3775 * @ingroup salld_api_functions
3776 * @brief Sa_chanGetBufferReq returns the memory requirements for an SALLD channel
3777 *
3778 * @details This function returns the memory buffer requirements in terms of the size and
3779 * alignment array. The SA Channel requires only one memory block as described below:
3780 * - SA Channel Instance: SA channel instance data
3781 *
3782 * @param[in] sizeCfg Size configuration information
3783 * @param[out] sizes Array of size requirements
3784 * @param[out] aligns Array of alignment requirements
3785 * @retval Value @ref salldRetCodes
3786 */
3787 int16_t Sa_chanGetBufferReq (Sa_ChanSizeCfg_t *sizeCfg, int sizes[], int aligns[]);
3789 /**
3790 * @ingroup salld_api_functions
3791 * @brief Sa_chanCreate creates the SALLD channel. It initializes an instance of SALLD
3792 * channel and its corresponding instance structure based on channel
3793 * configuration data such as the security protocol, and etc.
3794 *
3795 * @param[in] handle SALLD instance identifier.
3796 * @param[in] cfg Configuration information
3797 * @param[in] bases Array of the memory buffer base addresses
3798 * @param[out] pChanHdl Channel handle. This is a pointer to an initialized
3799 * instance structure.
3800 * @retval Value @ref salldRetCodes
3801 *
3802 * @note The channel buffers should be allocated from global accessible memory blocks and global
3803 * addresses should be used if this channel is expected to be shared among multiple cores.
3804 */
3805 int16_t Sa_chanCreate (Sa_Handle handle, Sa_ChanConfig_t *cfg, void* bases[],
3806 Sa_ChanHandle *pChanHdl);
3808 /**
3809 * @ingroup salld_api_functions
3810 * @brief Sa_chanClose decativates the SALLD channel. It clears the SALLD channel instance.
3811 * All the associated memory buffers can be freed after this call.
3812 *
3813 * @param[in] handle SALLD channel instance identifier
3814 * @param[out] bases Array of the memory buffer base addresses
3815 * @retval Value @ref salldRetCodes
3816 */
3817 int16_t Sa_chanClose (Sa_ChanHandle handle, void* bases[]);
3819 /**
3820 * @ingroup salld_api_functions
3821 * @brief This function controls the operations of a channel instance of SALLD. It is
3822 * used to configure and/or re-configure the SALLD channel with various control
3823 * information. This function should be called multiple times to configure and
3824 * activate the SALLD channel during the call setup period. Reconfiguration is
3825 * applicable for SRTP for re-key operations and there is no reconfiguration
3826 * supported for IPSec and Air Ciphering modes.
3827 *
3828 * @param[in] handle SALLD channel instance identifier.
3829 * @param[in] chanCtrlInfo Pointer to SALLD channel control config structure.
3830 * @retval Value @ref salldRetCodes
3831 *
3832 * @sa Sa_ChanCtrlInfo_t
3833 */
3834 int16_t Sa_chanControl (Sa_ChanHandle handle, Sa_ChanCtrlInfo_t *chanCtrlInfo);
3836 /**
3837 * @ingroup salld_api_functions
3838 * @brief This function activates the local channel instance at other DSP cores. It should
3839 * be called once at any other DSP cores which invoke the same SALLD channel that
3840 * is created and configured at the master core. It is up to the master core
3841 * to make the channel handle public and accessible by other DSP cores after
3842 * channel creation and configuration.
3843 * The following APIs are supported at slave cores.
3844 * - Sa_chanReceiveData
3845 * - Sa_chanSendData
3846 * - Sa_chanGetStats
3847 * - Sa_chanGetID
3848 *
3849 * @param[in] handle SALLD channel instance identifier.
3850 * @retval Value @ref salldRetCodes
3851 *
3852 * @note: This function should be called prior to other channel APIs
3853 * such as Sa_chanSendData() and Sa_chanReceiveData() are invoked
3854 *
3855 */
3856 int16_t Sa_chanStart (Sa_ChanHandle handle);
3858 /**
3859 * @ingroup salld_api_functions
3860 * @brief Sa_chanGetShadowHandle queries the shadow channel handle.
3861 *
3862 * @details This function returns the shadow channel handle. The shadow channel handle
3863 * is set to NULL if it does not exist. Refer to @ref appendix2 for details
3864 *
3865 * @param[in] handle The PA LLD channel instance identifier
3866 * @param[in] shandle Pointer to the shadow channel handle
3867 * @retval Value @ref salldRetCodes
3868 *
3869 */
3870 int16_t Sa_chanGetShadowHandle (Sa_ChanHandle handle, Sa_ChanHandle *shandle);
3872 /**
3873 * @ingroup salld_api_functions
3874 * @brief This utility function processes packets received from the network. It performs IPSec ESP specific
3875 * post-SA operations on the decrypted and/or integrity-verified data packet. It also
3876 * performs the actual decryption/authentication operation in SW-only mode.
3877 *
3878 * @param[in] info ESP Tx/Rx information pointer.
3879 * @param[in] pktDesc Pointer to the packet descriptor structure.
3880 * @retval Value @ref salldRetCodes
3881 *
3882 * @sa Sa_PktDesc_t
3883 */
3884 int16_t salld_esp_post_proc_util (salldIpsecEspTxRxInfo_t *info, Sa_PktDesc_t* pktDesc);
3886 /**
3887 * @ingroup salld_api_functions
3888 * @brief This function processes packets received from the network. It performs protocol-specific
3889 * post-SA operations on the decrypted and/or integrity-verified data packet. It also
3890 * performs the actual decryption/authentication operation in SW-only mode.
3891 *
3892 * @param[in] handle SALLD channel instance identifier.
3893 * @param[in] pktInfo Pointer to the packet info structure.
3894 * @retval Value @ref salldRetCodes
3895 *
3896 * @sa Sa_PktInfo_t
3897 */
3898 int16_t Sa_chanReceiveData (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo);
3901 /**
3902 * @ingroup salld_api_functions
3903 * @brief This utility function processes the data packet to the networks. It performs IPSec ESP specific
3904 * operations to prepare the data packets to be encrypted and/or authenticated by the SA.
3905 * It also performs the actual encryption and/or authentication in the SW-only mode
3906 *
3907 * @param[in] info ESP Tx/Rx information pointer.
3908 * @param[in] pktDesc Pointer to the packet descriptor structure.
3909 * @retval Value @ref salldRetCodes
3910 *
3911 * @sa Sa_PktDesc_t
3912 *
3913 */
3914 int16_t salld_esp_pre_proc_util (salldIpsecEspTxRxInfo_t *info, Sa_PktDesc_t* pktDesc);
3916 /**
3917 * @ingroup salld_api_functions
3918 * @brief This function processes the data packet to the networks. It performs protocol-specific
3919 * operations to prepare the data packets to be encrypted and/or authenticated by the SA.
3920 * It also performs the actual encryption and/or authentication in the SW-only mode
3921 *
3922 * @param[in] handle SALLD channel instance identifier.
3923 * @param[in] pktInfo Pointer to the packet info structure.
3924 * @param[in] clear Flag indicating whether to force non-encryption
3925 * @retval Value @ref salldRetCodes
3926 *
3927 * @sa Sa_PktInfo_t
3928 *
3929 */
3930 int16_t Sa_chanSendData (Sa_ChanHandle handle, Sa_PktInfo_t *pktInfo, uint16_t clear);
3933 /**
3934 * @ingroup salld_api_functions
3935 * @brief This function obtains SALLD channel protocol-specific statistics.
3936 *
3937 * @param[in] handle SALLD channel instance identifier.
3938 * @param[in] flags Various control flags @ref SALLDStatsCtrlBit
3939 * @param[in, out] stats Pointer to protocol-specific statistics
3940 * @retval Value @ref salldRetCodes
3941 */
3942 int16_t Sa_chanGetStats (Sa_ChanHandle handle, uint16_t flags, Sa_Stats_t *stats);
3944 /**
3945 * @ingroup salld_api_functions
3946 * @brief Sa_chanGetID returns the SA channel ID associated with the specified handle
3947 *
3948 * @details The function is called to request the SA channel ID corresponding to the handle.
3949 *
3950 * @param[in] handle SALLD instance identifier.
3951 * @retval Channel ID
3952 * @pre Sa_chanInit function should be called before calling this function
3953 */
3954 uint32_t Sa_chanGetID (Sa_ChanHandle handle);
3956 /**
3957 * @ingroup salld_api_functions
3958 * @brief Sa_chanGetSwInfo returns the SA-specific software information required for all packets
3959 * to be delivered to SA.
3960 *
3961 * @details It is an optional utility function to query the SA-specific software information in
3962 * both directions in case Sa_chanSendData() is not used and/or the callout function
3963 * ChanRegister() is not implemented.
3964 *
3965 * In normal operation, the from-network SWInfo will be passed to module user via callout
3966 * function ChanRegister() and the to-network SWInfo will be passed to module user via API
3967 * Sa_chanSendData().
3968 *
3969 * @param[in] handle SALLD channel instance identifier.
3970 * @param[in] dir Packet direction as specified at @ref Sa_PktDir_t
3971 * @param[in] pChanSwInfo Pointer to SALLD software routing information structure.
3972 * @retval Value @ref salldRetCodes
3973 *
3974 * @sa Sa_SWInfo_t
3975 *
3976 */
3977 int16_t Sa_chanGetSwInfo (Sa_ChanHandle handle, uint16_t dir, Sa_SWInfo_t* pChanSwInfo);
3980 /*@}*/ /* @name Channel APIs */
3982 /** @name Utility APIs
3983 *
3984 */
3985 /*@{*/
3987 /**
3988 * @ingroup salld_api_functions
3989 * @brief This function verifies whether the security context buffer has been freed
3990 * by SA.
3991 *
3992 * @param[in] scBuf Pointer to the Security Context buffer.
3993 * @retval TRUE if buffer is free; FALSE if otherwise
3994 *
3995 */
3996 uint16_t Sa_isScBufFree (uint8_t* scBuf);
3998 /**
3999 * @ingroup salld_api_constants
4000 * @brief Define the core dump collect buffer size in words (32 bit) supported by SASS.
4001 */
4002 #define sa_CORE_DUMP_BUF_SIZE 2048
4004 /**
4005 * @ingroup salld_api_functions
4006 * @brief This function snap shots the internal registers and scratch memory locations
4007 * for furt
4008 *
4009 * @param[in] handle SA system handle.
4010 * @param[in] dbgInfoBuf Debug information collection buffer pointer
4011 * @param[in] bufSize Debug information collection buffer size
4012 * @retval TRUE if collection is successful; FALSE if otherwise
4013 *
4014 * @warning Note that system is halted after @ref Sa_coreDump is initiated. After the call to this API,
4015 * it is up to the application software to redownload the firmware and restart SASS.
4016 *
4017 * @note This API is used to provide dump of internal data when requested by TI.
4018 * These can be submitted via e2e.ti.com or your contracted support vehicle.
4019 * When there is a JTAG connected to the system for collecting the data,
4020 * Please use the fprintf() code provided in the SaUnitTest application to save
4021 * the coredump, to avoid formatting issues.
4022 * There is also user space utility saCoreDumpUtil.out provided to collect
4023 * the debug information when requested from linux user space.
4024 */
4025 int16_t Sa_coreDump(Sa_Handle handle, uint32_t *dbgInfoBuf, uint16_t bufSize);
4028 /*@}*/ /* @name Utility APIs */
4030 /** @name SA LLD Macros
4031 *
4032 */
4033 /*@{*/
4035 /**
4036 * @ingroup salld_api_macros
4037 * @brief sa_MK_UINT32 is a simple utility macro which constructs a 32-bit word from 4 input bytes
4038 *
4039 * @param[in] a Input byte 1
4040 * @param[in] b Input byte 2
4041 * @param[in] c Input byte 3
4042 * @param[in] d Input byte 4
4043 *
4044 */
4045 #define sa_MK_UINT32(a, b, c, d) (((a) << 24) | ((b) << 16) | ((c) << 8) | (d))
4047 /**
4048 *
4049 * @ingroup salld_api_macros
4050 * @brief sa_mDmResetCmdLb: Reset the Command Label for Data Mode
4051 *
4052 * @details Inline macro API can be used to reset the Command Label
4053 * for Data Mode after first time initialization
4054 *
4055 * @param[in] updateInfo Command label updating control structure returned from SA LLD
4056 * @param[in] cmdLb Command Label Buffer
4057 *
4058 * @note: It is just a sample implemenation which should be optimized per use case
4059 */
4060 static inline
4061 void sa_mDmResetCmdLb(Sa_CmdLbUpdateInfo_t* updateInfo,
4062 uint32_t* cmdLb)
4063 {
4065 #ifdef NSS_LITE2
4066 cmdLb++;
4067 #endif
4069 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_ENC)
4070 {
4071 /* Clear the encSize and encOffset field to simplify the operation in command label updating Macros */
4072 cmdLb[updateInfo->encSizeInfo.index] &= 0xffff0000UL;
4073 cmdLb[updateInfo->encOffsetInfo.index] &= 0x00ffffffUL;
4074 }
4076 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUTH)
4077 {
4078 /* Clear the authSize and authOffset field to simplify the operation in command label updating Macros */
4079 cmdLb[updateInfo->authSizeInfo.index] &= 0xffff0000UL;
4080 cmdLb[updateInfo->authOffsetInfo.index] &= 0x00ffffffUL;
4081 }
4083 if ( (updateInfo->subMode == sa_DM_CCM) ||
4084 (updateInfo->subMode == sa_DM_CCM_GEN) )
4085 {
4086 /* Clear AAD length field */
4087 cmdLb[2] &= 0xffff0000UL;
4089 }
4090 }
4092 /**
4093 *
4094 * @ingroup salld_api_macros
4095 * @brief salld_form_32bits_util: form 32 bits command label from a byte array
4096 *
4097 * @details Inline macro API can be used to generate the 32 bits word array from
4098 * byte array as b[0]<<24 | b[1]<<16 | b[2] << 8 | b[3].
4099 *
4100 * @param[in] cmdLb Command Label Buffer
4101 * @param[in] index start index of cmdLb
4102 * @param[in] offset start offset in the cmdLb 32-bit word
4103 * @param[in] bPtr byte array pointer
4104 * @param[in] bSize byte array size
4105 *
4106 */
4107 static inline
4108 void salld_form_32bits_util(uint32_t* cmdLb, uint8_t index, uint8_t offset, uint8_t* bPtr, uint8_t bSize)
4109 {
4110 uint32_t temp = 0;
4111 int bIndex = 0;
4112 int8_t iShift = 8 *( 3 - offset);
4113 int w32Size, bytesInlast32bWord;
4115 /* number of bytes to be formed in last 32-bit word */
4116 bytesInlast32bWord = (bSize + offset ) & 3;
4118 /* number of bytes to be formed into full 32-bit words */
4119 w32Size = bSize - offset - bytesInlast32bWord;
4121 /* Handle the un-aligned first 32 word that needs update specially */
4122 if (offset != 0)
4123 {
4124 while (iShift >= 0) {
4125 temp |= bPtr[bIndex ++] << iShift;
4126 iShift -= 8;
4127 }
4128 cmdLb[index ++] |= temp;
4129 }
4131 /* the loop runs for all full 32-bit words */
4132 while (bIndex < w32Size)
4133 {
4134 cmdLb[index ++] = bPtr[bIndex] << 24 | bPtr[bIndex+1] << 16 | \
4135 bPtr[bIndex + 2] << 8 | bPtr[bIndex + 3];
4136 bIndex += 4;
4137 }
4139 /* Handle any un-handled (remaining) bytes towards the end */
4140 if (bytesInlast32bWord)
4141 {
4142 iShift = 24;
4143 temp = 0;
4144 while (bytesInlast32bWord) {
4145 temp |= bPtr[bIndex ++] << iShift;
4146 iShift -= 8;
4147 bytesInlast32bWord --;
4148 }
4149 cmdLb[index] = temp;
4150 }
4151 }
4153 /**
4154 *
4155 * @ingroup salld_api_macros
4156 * @brief sa_mDmUpdateCmdLb_ccm_gen: Update the command label for Data Mode in CCM general case
4157 *
4158 * @details Inline macro API can be used to update the command label per packet
4159 * for Data Mode during Encryption/Decryption request to SA.
4160 *
4161 * @param[in] encOffset Offset to the encrypted/decrypted data in the
4162 * packet in bytes
4163 * @param[in] encSize Number of bytes to be encrypted or decrypted
4164 * @param[in] pEncIV Initialization vectors if applicable for
4165 * encryption mode.
4166 * @param[in] aadSize Number of additional data to be authenticated in bytes
4167 * @param[in] aad Pointer to the additional authenticated data
4168 * @param[in] pCmdlUpdate Command label updating control structure returned from SA LLD
4169 * @param[in] cmdLb Command Label Buffer
4170 *
4171 * @note: It is just a sample implemenation for generic CCM use cases
4172 *
4173 */
4174 static inline
4175 void sa_mDmUpdateCmdLb_ccm_gen(uint8_t encOffset,
4176 uint16_t encSize,
4177 uint8_t* pEncIV,
4178 uint8_t aadSize,
4179 uint8_t* aad,
4180 Sa_CmdLbUpdateInfo_t* pCmdlUpdate,
4181 uint32_t* cmdLb)
4182 {
4183 uint8_t *iv = pEncIV;
4185 #ifdef NSS_LITE2
4186 cmdLb++;
4187 #endif
4189 /* Handle Option 1, (Option 2 & Option 3) in two different groups */
4190 /* Update the command label header (8 byte) */
4191 cmdLb[0] |= encSize;
4192 cmdLb[1] |= ((uint32_t)encOffset << 24);
4194 /* Option 1 Update: if AAD size is 0, no updates to Option 1 */
4195 if ( (aadSize > 0) &&
4196 (aadSize <= 14) )
4197 {
4198 /* Option 1: B1 (aadlen | AAD ) (16 byte) */
4199 /* update AAD */
4200 salld_form_32bits_util(&cmdLb[0], pCmdlUpdate->aadInfo.index, \
4201 pCmdlUpdate->aadInfo.offset, &aad[0], aadSize);
4202 }
4204 /* Option 2 update IV: B0 (flag | salt | IV | encypted data len) (16 byte) */
4205 salld_form_32bits_util(&cmdLb[0], pCmdlUpdate->encIvInfo.index, \
4206 pCmdlUpdate->encIvInfo.offset, iv, pCmdlUpdate->encIvInfo.size);
4208 cmdLb[9] &= 0xFFFF0000UL; /* Clear the lower 16 bits */
4209 cmdLb[9] |= encSize; /* Set with encoder size */
4211 /* Option 3: AES-CTR IV (salt| IV | 0) (16 byte) */
4212 /* Insert IV and encrypted data len */
4213 /* IV1 & 2*/
4214 cmdLb[10] = cmdLb[6] & 0x07FFFFFFUL;
4215 cmdLb[11] = cmdLb[7];
4216 cmdLb[12] = cmdLb[8];
4217 cmdLb[13] = cmdLb[9] & 0xFFFF0000UL;
4218 }
4220 /**
4221 *
4222 * @ingroup salld_api_macros
4223 * @brief sa_mDmUpdateCmdLb_ccm_wimax: Update the command label for CCM-WiMax
4224 *
4225 * @details Inline macro API can be used to update the command label per packet
4226 * for Data Mode during Encryption/Decryption request to SA.
4227 *
4228 * @param[in] encOffset Offset to the encrypted/decrypted data in the
4229 * packet in bytes
4230 * @param[in] encSize Number of bytes to be encrypted or decrypted
4231 * @param[in] gmh generic mac header pointer.
4232 * @param[in] sn sequence number pointer
4233 * @param[in] cmdLb Command Label Buffer
4234 *
4235 * @note: It is just a sample implemenation for CCM-WiMax (optimal implementation)
4236 *
4237 */
4238 static inline
4239 void sa_mDmUpdateCmdLb_ccm_wimax (
4240 uint8_t encOffset,
4241 uint16_t encSize,
4242 uint8_t* gmh, /* 5 bytes (excluding HCS (header check sequence) */
4243 uint8_t* sn, /* 4 bytes of sequence number */
4244 uint32_t* cmdLb)
4245 {
4247 #ifdef NSS_LITE2
4248 cmdLb++;
4249 #endif
4251 cmdLb[0] |= encSize;
4252 cmdLb[1] |= ((uint32_t)encOffset << 24);
4254 /* AAD (none) */
4256 /* Option 2: B0 (flag | nonce | encypted data len) (16 byte) */
4257 /* Insert IV and encrypted data len */
4258 cmdLb[6] |= ((gmh[0] << 16) | \
4259 (gmh[1] << 8) | \
4260 (gmh[2]) );
4261 cmdLb[7] = ((gmh[3] << 24) | (gmh[4] << 16));
4262 cmdLb[8] = ((sn[0] << 8) | (sn[1]));
4263 cmdLb[9] = ((sn[2] << 24) | (sn[3] << 16) | encSize);
4265 /* Option 3: AES-CTR IV (flag | nonce | 0) (16 byte) */
4266 cmdLb[10] = cmdLb[6] & 0x07FFFFFFUL;
4267 cmdLb[11] = cmdLb[7];
4268 cmdLb[12] = cmdLb[8];
4269 cmdLb[13] = cmdLb[9] & 0xFFFF0000UL;
4270 }
4272 /**
4273 *
4274 * @ingroup salld_api_macros
4275 * @brief sa_mDmUpdateCmdLb: Update the command label for Data Mode for IPSEC,SRTP
4276 *
4277 * @details Inline macro API can be used to update the command label per packet
4278 * for Data Mode during Encryption/Decryption request to SA.
4279 *
4280 * @param[in] encOffset Offset to the encrypted/decrypted data in the
4281 * packet in bytes
4282 * @param[in] encSize Number of bytes to be encrypted or decrypted
4283 * @param[in] pEncIV Initialization vectors if applicable for
4284 * encryption mode.
4285 * @param[in] authOffset Offset to the (To be) authenticated data in the
4286 * packet in bytes
4287 * @param[in] authSize Number of bytes to be authenticated
4288 * @param[in] pAuthIV Initialization vectors if applicable for
4289 * authentication modes.
4290 * @param[in] aadSize Number of additional data to be authenticated in bytes
4291 * @param[in] aad Pointer to the additional authenticated data
4292 * @param[in] pDataBuf Pointer to data buffer
4293 * @param[in] updateInfo Command label updating control structure returned from SA LLD
4294 * @param[in] cmdLb Command Label Buffer
4295 *
4296 * @note: It is just a sample implemenation for below use cases:
4297 * IPSEC
4298 * SRTP
4299 *
4300 */
4301 static inline
4302 void sa_mDmUpdateCmdLb(uint8_t encOffset,
4303 uint16_t encSize,
4304 uint8_t* pEncIV,
4305 uint8_t authOffset,
4306 uint16_t authSize,
4307 uint8_t* pAuthIV,
4308 uint8_t aadSize,
4309 uint8_t* aad,
4310 uint8_t* pDataBuf,
4311 Sa_CmdLbUpdateInfo_t* updateInfo,
4312 uint32_t* cmdLb)
4313 {
4314 #ifdef NSS_LITE2
4315 cmdLb++;
4316 #endif
4318 switch (updateInfo->subMode)
4319 {
4320 case sa_DM_GEN: /* General Mode operation */
4321 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_ENC)
4322 {
4323 cmdLb[updateInfo->encSizeInfo.index] |= encSize;
4324 cmdLb[updateInfo->encOffsetInfo.index] |= ((uint32_t)encOffset << 24);
4326 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_ENC_IV)
4327 {
4328 uint32_t *data = &cmdLb[updateInfo->encIvInfo.index];
4329 uint8_t *iv = pEncIV;
4331 data[0] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
4332 data[1] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
4334 if (updateInfo->encIvInfo.size > 8)
4335 {
4336 data[2] = sa_MK_UINT32(iv[8], iv[9], iv[10], iv[11]);
4337 data[3] = sa_MK_UINT32(iv[12], iv[13], iv[14], iv[15]);
4338 }
4339 }
4340 }
4342 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUTH)
4343 {
4344 cmdLb[updateInfo->authSizeInfo.index] |= authSize;
4345 cmdLb[updateInfo->authOffsetInfo.index] |= (authOffset << 24);
4347 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUTH_IV)
4348 {
4349 uint32_t *data = &cmdLb[updateInfo->authIvInfo.index];
4350 uint8_t *iv = pAuthIV;
4352 data[0] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
4353 data[1] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
4355 if (updateInfo->authIvInfo.size > 8)
4356 {
4357 data[2] = sa_MK_UINT32(iv[8], iv[9], iv[10], iv[11]);
4358 data[3] = sa_MK_UINT32(iv[12], iv[13], iv[14], iv[15]);
4359 }
4360 }
4362 if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_AUX_KEY)
4363 {
4365 int offset = (authSize & 0xF)?4:0;
4366 memcpy(&cmdLb[updateInfo->auxKeyInfo.index], &updateInfo->auxKey[offset], 16);
4367 }
4368 }
4369 break;
4372 case sa_DM_CCM:
4373 {
4374 uint8_t *iv = pEncIV;
4376 cmdLb[0] |= encSize;
4377 cmdLb[1] |= ((uint32_t)encOffset << 24);
4379 /* AAD */
4380 cmdLb[2] |= ((aad[0] << 8) + aad[1]);
4381 cmdLb[3] = sa_MK_UINT32(aad[2], aad[3], aad[4], aad[5]);
4382 if (aadSize == 8)
4383 {
4384 cmdLb[4] = (aad[6] << 24) + (aad[7] << 16);
4385 }
4386 else
4387 {
4388 cmdLb[4] = sa_MK_UINT32(aad[6], aad[7], aad[8], aad[9]);
4389 cmdLb[5] = (aad[10] << 24) + (aad[11] << 16);
4390 }
4392 /* IV1 & 2*/
4393 cmdLb[11] = cmdLb[7] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
4394 cmdLb[12] = cmdLb[8] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
4396 /* data length 2 */
4397 cmdLb[9] = encSize;
4399 }
4400 break;
4402 case sa_DM_GCM:
4403 {
4405 uint8_t *iv = pEncIV;
4407 cmdLb[0] |= encSize;
4408 cmdLb[1] |= ((uint32_t)encOffset << 24);
4410 /* AAD */
4411 cmdLb[4] = sa_MK_UINT32(aad[0], aad[1], aad[2], aad[3]);
4412 cmdLb[5] = sa_MK_UINT32(aad[4], aad[5], aad[6], aad[7]);
4413 if (aadSize == 12)
4414 {
4415 cmdLb[6] = sa_MK_UINT32(aad[8], aad[9], aad[10], aad[11]);
4416 }
4418 /* IV */
4419 cmdLb[9] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
4420 cmdLb[10] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
4422 /* data length 2 */
4423 cmdLb[3] = encSize << 3;
4425 }
4426 break;
4428 case sa_DM_GMAC:
4429 {
4430 uint8_t *iv = pAuthIV;
4431 uint8_t *payload = pDataBuf + authOffset;
4432 uint8_t dataAppended = 16 - aadSize; /* payload appended to AAD in bytes */
4434 cmdLb[0] |= authSize - dataAppended;
4435 cmdLb[1] |= ((authOffset + dataAppended) << 24);
4437 /* AAD */
4438 cmdLb[4] = sa_MK_UINT32(aad[0], aad[1], aad[2], aad[3]);
4439 cmdLb[5] = sa_MK_UINT32(aad[4], aad[5], aad[6], aad[7]);
4440 if (aadSize == 8)
4441 {
4442 cmdLb[6] = sa_MK_UINT32(payload[0], payload[1], payload[2], payload[3]);
4443 cmdLb[7] = sa_MK_UINT32(payload[4], payload[5], payload[6], payload[7]);
4444 }
4445 else
4446 {
4447 cmdLb[6] = sa_MK_UINT32(aad[8], aad[9], aad[10], aad[11]);
4448 cmdLb[7] = sa_MK_UINT32(payload[0], payload[1], payload[2], payload[3]);
4449 }
4451 /* IV */
4452 cmdLb[9] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
4453 cmdLb[10] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
4455 /* data length 2 */
4456 cmdLb[3] = (authSize + aadSize) << 3;
4458 }
4459 break;
4461 case sa_DM_GMAC_AH:
4462 {
4463 uint8_t *iv = pAuthIV;
4465 cmdLb[0] |= authSize;
4466 cmdLb[1] |= (authOffset << 24);
4468 /* data length 2 */
4469 cmdLb[3] = (authSize) << 3;
4471 /* IV */
4472 cmdLb[5] = sa_MK_UINT32(iv[0], iv[1], iv[2], iv[3]);
4473 cmdLb[6] = sa_MK_UINT32(iv[4], iv[5], iv[6], iv[7]);
4475 }
4476 break;
4479 default:
4480 /* Error handling */
4481 break;
4482 }
4483 }
4485 /**
4486 * @ingroup salld_api_structures
4487 * @brief Sa_psInfo_t defines the PS Info data used by SASS
4488 *
4489 * @details Sa_psInfo_t defines the Protocol-specific information required by SASS
4490 * - word[0] contains command, payload offset and payload length described below:
4491 * -SRTP/AC: offset to the RTP header; RTP payload length including ICV
4492 * -IPSEC AH: offset to the Outer IP; IP payload length
4493 * -IPSEC ESP: offset to the ESP header; ESP papload length including ICV
4494 * - word[1] contains 32-bit count-C for certain 3GPP ciphering and encryption modes
4495 * - word[2:5] contain up to 16-byte IV in array of 32-bit words for certain 3GPP
4496 * ciphering and encryption modes
4497 * @note: Use PS Info constructing Macros to format the PS Info data
4498 */
4500 typedef struct {
4501 uint32_t word[6]; /**< PS Info control block word 0-5 */
4502 } Sa_psInfo_t;
4504 /**
4505 * @ingroup salld_api_macros
4506 * @{
4507 * @name SA PS Info Constructing Macros
4508 * Macros used by the SA PS Info Command
4509 *
4510 */
4511 /*@{*/
4512 #define sa_PSINFO_FORMAT_CMD(x, offset, len) ((x)->word[0] = (0x20000000UL | ((offset) << 16) | (len))) /**< Format the PS Info header */
4513 #define sa_PSINFO_SET_COUNTC(x, countC) ((x)->word[1] = (countC)) /**< Constructing Count-C */
4514 static inline void sa_PSINFO_SET_IV(Sa_psInfo_t *x, uint32_t *iv, int ivSize) /**< Constructing IV */
4515 {
4516 int i;
4517 x->word[0] |= ((ivSize + 8) << 24);
4518 for( i = 0; i < ivSize/4 ; i++)
4519 x->word[i+ 2] = iv[i];
4520 }
4521 /*@}*/
4522 /** @} */
4524 /* @} */ /* ingroup */
4526 /*@}*/ /* @name SA LLD Macros */
4529 /**
4530 * @page appendix1 3GPP Opeartion and PDU formats
4531 *
4532 * There are many variation of PDU formats specified by the various 3GPP Protocols.
4533 * All supported 3GPP operations and data formats are described below:
4534 *
4535 * @par GSM:
4536 * Supported PDU types:
4537 *
4538 * @verbatim
4541 0 1 2 3 4 5 6 7
4542 +-+-+-+-+-+-+-+-+
4543 | |
4544 + IV (8/16byte) |
4545 | |
4546 +>+-+-+-+-+-+-+-+-+
4547 | | |
4548 | | |
4549 | | Data |
4550 | | |
4551 | | |
4552 | +-+-+-+-+-+-+-+-+
4553 |
4554 |-> Ciphering Unit
4556 Figure 1. Ciphering Unit of a GSM PDU.
4557 @endverbatim
4558 *
4559 * @par
4560 * Ciphering algorithm: GSM A5/3, ECSD A5/3, GAE3, Kasumi-F8
4561 * @par
4562 * Key Stream Generation:
4563 * - Input to SA: 64-bit IV plus all zero payload
4564 * - 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)
4565 * @par
4566 * Full Encryption/Decryption:
4567 * - Input to SA: 64/128-bit IV plus payload
4568 * - Output from SA: 64/128-bit IV plus encryped/decrypted paylaod
4569 *
4570 * @par WCDMA:
4571 * Supported PDU types:
4572 *
4573 * @verbatim
4576 0 1 2 3 4 5 6 7
4577 +-+-+-+-+-+-+-+-+
4578 |DC| Seq Num |
4579 +-+-+-+-+-+-+-+-+
4580 |Seq Num |P| HE|
4581 +>+-+-+-+-+-+-+-+-+
4582 | | Length Ind. |E|
4583 | +-+-+-+-+-+-+-+-+
4584 | | |
4585 | | |
4586 | | Data |
4587 | | |
4588 | | |
4589 | +-+-+-+-+-+-+-+-+
4590 | | PAD or piggy-backed STATUS PDU
4591 | +-+-+-+-+-+-+-+-+
4592 |
4593 |-> Ciphering Unit
4596 Figure 2. Ciphering Unit of a WCDMA AMD PDU.
4599 0 1 2 3 4 5 6 7
4600 +-+-+-+-+-+-+-+-+
4601 | Seq Num |E|
4602 +>+-+-+-+-+-+-+-+-+
4603 | | Length Ind. |E|
4604 | +-+-+-+-+-+-+-+-+
4605 | | |
4606 | | |
4607 | | Data |
4608 | | |
4609 | | |
4610 | +-+-+-+-+-+-+-+-+
4611 |
4612 |-> Ciphering Unit
4615 Figure 3. Ciphering Unit of a WCDMA UMD PDU.
4618 0 1 2 3 4 5 6 7
4619 +-+-+-+-+-+-+-+-+
4620 | |
4621 | Count-C |
4622 | (4-byte) |
4623 | |
4624 +>+-+-+-+-+-+-+-+-+
4625 | | |
4626 | | |
4627 | | Data |
4628 | | |
4629 | | |
4630 | +-+-+-+-+-+-+-+-+
4631 |
4632 |-> Ciphering Unit
4634 Figure 4. Ciphering Unit of a WCDMA TMD PDU.
4635 @endverbatim
4637 *
4638 * @par
4639 * Ciphering algorithm: Kasumi/F8,Snow 3G/F8, AES-CTR
4640 *
4641 * @par
4642 * From Air Traffic (Decryption) :
4643 * - Input to SA:
4644 * - PDU header plus payload for RLC AMD/UMD PDU
4645 * - Payload with 32-bit Count-C in the CPPI header for TMD MAC PDU
4646 * - Output from SA:
4647 * - PDU header plus decrypted payload for RLC AMD/UMD PDU
4648 * - Decrypted payload for TMD MAC PDU
4649 *
4650 * @par
4651 * To Air Traffic (Encryption) :
4652 * - Input to SA:
4653 * - PDU header plus payload for RLC AMD/UMD PDU
4654 * - Payload for TMD MAC PDU
4655 * - Output from SA:
4656 * - PDU header plus encrypted payload for RLC AMD/UMD PDU
4657 * - 32-bit Count-C plus encrypted payload for TMD MAC PDU
4658 *
4659 *
4660 * @par LTE:
4661 * Supported PDU types:
4662 *
4663 * @verbatim
4665 0 1 2 3 4 5 6 7
4666 +-+-+-+-+-+-+-+-+
4667 | |
4668 | Count-C |
4669 | (4-byte) |
4670 | |
4671 +>+-+-+-+-+-+-+-+-+
4672 | | |
4673 | | |
4674 | | Data |
4675 | | |
4676 | | |
4677 | +-+-+-+-+-+-+-+-+
4678 |
4679 |-> Ciphering Unit
4681 Figure 5. Ciphering Unit of a PDCP Data PDU.
4684 0 1 2 3 4 5 6 7
4685 +-+-+-+-+-+-+-+-+ <+
4686 |R R R| PDCP SN | |
4687 +>+-+-+-+-+-+-+-+-+ |
4688 | | | |
4689 | | | |
4690 | | Data | |
4691 | | | |
4692 | | | |
4693 | +-+-+-+-+-+-+-+-+ |-> Authentication Unit
4694 | | MAC-I |
4695 | | (4 byte) |
4696 | +-+-+-+-+-+-+-+-+
4697 |
4698 |-> Ciphering Unit
4700 Figure 6. PDCP Control Plane Data Uint for SRBs
4701 @endverbatim
4702 *
4703 * @par
4704 * Ciphering algorithm: Snow 3G/F8, AES-CTR
4705 * Authentication algorithm: CMAC
4706 *
4707 * @par
4708 * From Air Traffic (Decryption and/or Authentication verification) :
4709 * - Input to SA:
4710 * - PDCP Data with 32-bit Count-C in the CPPI header for the Data Plane PDU
4711 * - PDCP Header plus Data and MAC-I with 32-bit Count-C in the CPPI header for the Control Plane PDU
4712 * - Output from SA: 32-bit Count-C plus decrypted PDCP PDU Data
4713 * - PDCP Data for the Data Plane PDU
4714 * - PDCP Header plus Data and MAC-I for the Control Plane PDU
4715 *
4716 * @par
4717 * To Air Traffic (Encryption and/or Authentication) :
4718 * - Input to SA:
4719 * - PDCP Data for the Data Plane PDU
4720 * - PDCP Header plus Data and MAC-I with 32-bit Count-C in the CPPI header for the Control Plane PDU
4721 * - Output from SA: 32-bit Count-C plus encrypted PDCP PDU Data
4722 * - 32-bit Count-C plus PDCP Data for the Data Plane PDU
4723 * - PDCP Header plus Data and MAC-I for the Control Plane PDU
4724 */
4726 /**
4727 * @page appendix2 Shadow Instance for mixed-Endian operation
4728 *
4729 * The SASS supports mixed-endianess operating mode such that the channel is created and configured by the master
4730 * processor, (e.g. ARM which is outside of SoC), while the data processing is handled by slave processor(s)
4731 * (e.g. DSPs). When in this mode, SA LLD must create and maintain a shadow instance, which is a copy of
4732 * the master instance with opposite endianess. New APIs are created to query the shadow instances, which should be
4733 * passed to and used by the slave processor(s).
4734 *
4735 * @note: Only the following use case is supported at this moment, further enhancements may be provided:
4736 * - IPSEC ESP/AH mode
4737 * - Control Path at ARM and Data Path at DSPs
4738 *
4739 */
4741 /**
4742 * @page appendix3 SA2_UL Requirements for packet to pass Security Attributes Checkes
4743 *
4744 * In addition to the first-level check that the context fetch must pass is to satisfy
4745 * the external firewall module's check at the soc level configured by DMSC, the second-level check
4746 * that SA2_UL does is to compare the incoming packet\92s security attributes
4747 * against the attributes that are stored as part of the SCCTL inside the security context.
4748 * The following table summarizes the evaluation that will occur before a context is used for the packet
4749 * processing. The rightmost column shows the possible change in 'secure' attribute of the packet
4750 * if and only if the check passes. If packet check fails, the original packet attribute is untouched.
4751 *
4752 * @verbatim
4753 * |----------------------------------------------------|-------------------------------------------------|----------------|
4754 * | Incoming Packet Attributes | Attributes in Security Context | |
4755 * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------| Impact |
4756 * | Secure | Promote | Demote | NS | Priv | PrivID | Ctx | Ctx | Ctx | Ctx | Priv | PrivID | on out |
4757 * | | | | Crypto | | | Secure | Promote | Demote | NS | | | pkt attributes |
4758 * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
4759 * | 0 | 0 | 0 | 0 | b | c | 0 | 0 | 0 | 0 | b | c | No Change |
4760 * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
4761 * | 1 | 0 | 0 | 0 | b | c | 1 | 0 | 0 | 0 | b | c | No Change |
4762 * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
4763 * | 0 | 1 | 0 | 0 | b | c | 1 | 1 | 0 | 0 | b | c | Secure=1(note2)|
4764 * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
4765 * | 1 | 0 | 1 | 0 | b | c | 1 | 0 | 1 | 0 | b | c | Secure=0(note3)|
4766 * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
4767 * | 0 | 0 | 0 | 1 | b | c | 1 | 0 | 0 | 1 | b | c |No Change(note4)|
4768 * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
4769 *
4770 * @endverbatim
4771 * Legend:
4772 * The 'b' and 'c' can be any legal value of 2-bit priv and 8-bit privid respectively. The priv attribute on the
4773 * input packet must match the priv attribute in the context. Similarly the privid attribute on the input packet
4774 * must match the privid attribute in the context, except when the privid in the context is using the wildcard
4775 * value (0xC3) which will bypass the privid check.
4776 * Note 1: Promotion of non-secure packet to be secure packet also always requires the 48-bit SCPTR that
4777 * comes with the packet to be within the range of 'SCPTR Promote Range' registers.
4778 * Note 2: Output packet (with secure attribute = 1) is intended to land in a secure memory.
4779 * Note 3: Output packet (with secure attribute = 0) is intended to land in a non-secure memory.
4780 * Note 4: When the input packet has NS_crypto = 1 and the context has AllowNS = 1, a non-secure packet
4781 * is allowed to use a secure context without knowing the key, but the output packet is intended to land in a
4782 * non-secure memory (secure attribute on the packet stays at 0).
4783 * Any other attributes combinations from the table above will result in security exceptions.
4784 *
4785 */
4787 #ifdef __cplusplus
4788 }
4789 #endif
4791 #endif /* _SALLD_H */
4793 /* nothing past this point */