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