2890 lines
110 KiB
C
2890 lines
110 KiB
C
/* ipmacsec.h - MACsec Public header file */
|
|
/*
|
|
* Copyright (c) 2010 Wind River Systems, Inc.
|
|
*
|
|
* The right to copy, distribute, modify, or otherwise make use
|
|
* of this software may be licensed only pursuant to the terms
|
|
* of an applicable Wind River license agreement.
|
|
*
|
|
*/
|
|
|
|
/*
|
|
modification history
|
|
--------------------
|
|
01a,08feb10,mry Created
|
|
*/
|
|
#ifndef IPMACSEC_H
|
|
#define IPMACSEC_H
|
|
|
|
/*
|
|
\h DESCRIPTION
|
|
|
|
This header file is to be included by external and internal modules interfacing to ipmacsec.
|
|
It defines the public structures and APIs for the ipmacsec module.
|
|
|
|
The LMI APIs (ipmacsec_lmi_xxx) are the Public APIs that can be used by KaY, network management,
|
|
or other 3rd party software interfacing with the MACsec software.
|
|
|
|
\h IPMACSEC Buffer container
|
|
|
|
The Ipmacsec_buffer container encapsulates and abstracts the data buffer manipulation when interfacing with the LMI API.
|
|
|
|
The ipmacsec_buf_xxx() API or IPMACSEC_BUF_XXX macros are used to manipulate the Ipmacsec_buffer container.
|
|
The detailed description of the ipmacsec_buf_xxx() API and IPMACSEC_BUF_XXX macros is listed below.
|
|
|
|
`Usage Example'
|
|
Here is a typical usage example pseudocode (Note that this example does not include error handling or return code checking):
|
|
\cs
|
|
Ipmacsec_buffer buf; // Allocate the buffer container on the stack.
|
|
IPMACSEC_BUF_INIT(&buf); // Initialize the buffer container before using it.
|
|
ipmacsec_buf_alloc(&buf, <size>); // Allocate the buffer data
|
|
ipmacsec_buf_append(&buf, <data>, <len>); // (Optionally) Append to the buffer contents.
|
|
ipmacsec_lmi_xxx(..., &buf, ...) // call an LMI API that will parse/update the buffer contents.
|
|
Ip_u32 remlen; Ip_u8 *dataptr = ipmacsec_buf_ptr(&buf, <offset>, &remlen); // Retrieve pointer to data at specified offset
|
|
ipmacsec_buf_free(&buf); // Free the buffer data
|
|
\ce
|
|
Alternately, instead of calling ipmacsec_buf_alloc(), ipmacsec_buf_set() may be used to set the data buffer to a preallocated
|
|
data buffer or a stack buffer region. Note that when ipmacsec_buf_set() is used, the subsequent ipmacsec_buf_free() will
|
|
not free the data buffer which is in this case the responsibility of the calling code.
|
|
|
|
ipmacsec_buf_wipe() can be used to clear the buffer contents and reset the container without freeing the data buffer.
|
|
|
|
For more detailed examples including error handling, refer to "ipmacsec_lmi.c".
|
|
|
|
\h SecY Secure Association Keys (SAKs)
|
|
You can only install as many keys as there are allowed SAs (total TX + RX).
|
|
Thus an SA key needs to be deleted before another one is installed for the same AN,
|
|
otherwise the keydb may become full and further key installs will fail.
|
|
IPMACSEC_SECY_KEYDB_SIZE defines the maximum # of keys that can be installed per SecY.
|
|
|
|
\h Common macros:
|
|
|
|
IPMACSEC_INVALIDATE_SCI(sci) - initializes the sci to an invalid value. Has no return value
|
|
IPMACSEC_COPY_SCI(dest,src) - copies the src SCI to the dest SCI. Has no return value
|
|
IPMACSEC_SCI_MATCH(sci1,sci2) - compares two sci value. returns TRUE if equal, FALSE otherwise
|
|
|
|
IPMACSEC_COPY_CIPHER_SUITE_ID(dest,src) - copies the cipher suite id src to the dest. Has no return value
|
|
|
|
IPMACSEC_BOOL_STRING(boolval) - returns a string describing the supplied boolean value
|
|
IPMACSEC_DIR_STRING(dir) - returns a string describing the supplied MACsec Ipmacsec_dir direction value
|
|
|
|
\h Time related manipulation macros:
|
|
|
|
IPMACSEC_TIMEBUF(tbuf) - Initialize a stack buffer to hold the time string
|
|
IPMACSEC_STRFTIME(tbuf, time) - Covert time value to a string stored in tbuf
|
|
|
|
`Usage example:'
|
|
`============'
|
|
\cs
|
|
Ipmacsec_time time = <something>;
|
|
IPMACSEC_TIMEBUF(tbuf);
|
|
IPMACSEC_STRFTIME(tbuf, time);
|
|
printf("time: %s\n", tbuf);
|
|
\ce
|
|
|
|
*/
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 2 CONFIGURATION
|
|
****************************************************************************
|
|
*/
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 3 INCLUDE FILES
|
|
****************************************************************************
|
|
*/
|
|
#ifdef IP_PORT_VXWORKS
|
|
#include <vsbConfig.h>
|
|
#endif
|
|
|
|
#include <ipcom_type.h>
|
|
#include <ipcom_cstyle.h>
|
|
|
|
#include <ipnet_netif.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 4 DEFINES
|
|
****************************************************************************
|
|
*/
|
|
#ifdef _WRS_CONFIG_IPMACSEC_STATS
|
|
#ifndef IPMACSEC_USE_STATS
|
|
/* IPMACSEC_USE_STATS is used to enable MACsec statistics gathering and reporting */
|
|
#define IPMACSEC_USE_STATS
|
|
#endif
|
|
#endif
|
|
|
|
#define IPMACSEC_AN_MAX_VAL 3 /* Valid AN values are 0-3 (DO NOT CHANGE THIS) */
|
|
#define IPMACSEC_MAX_SA_NUM (IPMACSEC_AN_MAX_VAL+1) /* Absolute limit on maximum # of SAs (DO NOT CHANGE THIS) */
|
|
#define IPMACSEC_MAX_SC_NUM 256 /* Absolute limit on maximum # of supported SCs (DO NOT CHANGE THIS).
|
|
* Note that this includes the TX SC and RX SCs, so max RX SCs are
|
|
* one less than this value */
|
|
|
|
#define IPMACSEC_MAX_RX_SC 1 /* maximum # of supported RX SCs in this release (must be <= IPMACSEC_MAX_SC_NUM-1). */
|
|
#if (IPMACSEC_MAX_RX_SC > IPMACSEC_MAX_SC_NUM-1)
|
|
#error Invalid value for IPMACSEC_MAX_RX_SC
|
|
#endif
|
|
|
|
#define IPMACSEC_MAX_SA 2 /* maximum # of supported SAs in this release (must be <= IPMACSEC_MAX_SA_NUM) */
|
|
#if (IPMACSEC_MAX_SA > IPMACSEC_MAX_SA_NUM)
|
|
#error Invalid value for IPMACSEC_MAX_SA
|
|
#endif
|
|
|
|
/* This is the default manadatory cipher suite specified in IEEE 802.1AE */
|
|
#define IPMACSEC_DEFAULT_CIPHER_SUITE IPMACSEC_CIPHERSUITE_GCM_AES_128
|
|
|
|
/* This is the Cipher Suite ID for the GCM-AES-128 cipher suite (14.4: Table 14-1) */
|
|
#define IPMACSEC_CIPHER_SUITE_ID_GCM_AES_128 {0x00, 0x80, 0x02, 0x00, 0x01, 0x00, 0x00, 0x01}
|
|
|
|
#define IPMACSEC_SECY_KEYDB_SIZE (IPMACSEC_MAX_SA*(IPMACSEC_MAX_RX_SC+1)) /* See description section */
|
|
|
|
#define IPMACSEC_SCI_LEN 8 /* # of octets in the SCI field */
|
|
|
|
#define IPMACSEC_MAX_SECTAG_LEN (IPMACSEC_SCI_LEN+8) /* Max # of octets in the Sectag field */
|
|
|
|
#define IPMACSEC_MAX_ICV_LEN 16 /* Max # of octets in the ICV field */
|
|
|
|
#define IPMACSEC_CIPHER_SUITE_ID_LEN 8 /* # of octets in the Cipher Suite ID field */
|
|
|
|
#define IPMACSEC_CIPHER_SUITE_NAME_LEN 64 /* # of octets available for name string including Null terminator */
|
|
|
|
/* Layer Management Interface handle */
|
|
#define IPMACSEC_LMI_HANDLE void *
|
|
|
|
/* Max # of octets to reserve in a packet for MACsec (Sectag Header, ICV) */
|
|
#define IPMACSEC_RESERVED_OCTETS (IPMACSEC_MAX_SECTAG_LEN+IPMACSEC_MAX_ICV_LEN)
|
|
|
|
|
|
/* IPMACSEC Buffer manipulation macros:
|
|
* ===================================
|
|
* Some of these macros are provided for convenience as alternative to the ipmacsec_buf_xxx api.
|
|
* Use the corresponding API (where applicable) if you care about return values.
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_INIT - MACRO used to initialize a buffer container before allocating and using it
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_INIT(buf)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: pointer to an ipmacsec_buffer container that has not been allocated.
|
|
* \ie
|
|
* DESCRIPTION
|
|
* Zeroes out the buffer contents, including the data pointer. Has no return value.
|
|
* WARNING:
|
|
* IPMACSEC_BUF_INIT() MUST only be called on an unallocated buffer container
|
|
* (i.e. before IPMACSEC_BUF_ALLOC() is called), otherwise if a container has an allocated buffer,
|
|
* memory leaks will occur. Also IPMACSEC_BUF_INIT() MUST be called for all buffer containers
|
|
* before any of the other APIs are called to make sure its contents are properly initialized and
|
|
* do not contain uninitialized values that may cause problems and possible traps.
|
|
*****************************************************************************/
|
|
#define IPMACSEC_BUF_INIT(buf) (void)ipcom_memset((buf), 0, sizeof(Ipmacsec_buffer))
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_ALLOC - MACRO equivalent of ipmacsec_buf_alloc() but with no return value
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_ALLOC(buf,size)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A buffer container initialized with IPMACSEC_BUF_INIT() or one previously freed.
|
|
* Passing an already allocated buffer container will result in an error.
|
|
* \i <size>: Size of data to allocate (in bytes)
|
|
* \ie
|
|
* DESCRIPTION
|
|
* See ipmacsec_buf_alloc().
|
|
* SEE ALSO:
|
|
* ipmacsec_buf_alloc()
|
|
*****************************************************************************/
|
|
#define IPMACSEC_BUF_ALLOC(buf,size) (void)ipmacsec_buf_alloc(buf,size)
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_WIPE - MACRO equivalent of ipmacsec_buf_wipe() but with no return value
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_WIPE(buf)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A valid buffer container
|
|
* \ie
|
|
* DESCRIPTION
|
|
* See ipmacsec_buf_wipe().
|
|
* SEE ALSO:
|
|
* ipmacsec_buf_wipe()
|
|
*****************************************************************************/
|
|
#define IPMACSEC_BUF_WIPE(buf) (void)ipmacsec_buf_wipe(buf)
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_APPEND - MACRO equivalent of ipmacsec_buf_append() but with no return value
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_APPEND(buf,ptr,len)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A valid allocated buffer container
|
|
* \i <ptr>: An optional pointer to the data to append
|
|
* \i <len>: Length of data to append
|
|
* \ie
|
|
* DESCRIPTION
|
|
* See ipmacsec_buf_append().
|
|
* SEE ALSO:
|
|
* ipmacsec_buf_append()
|
|
*****************************************************************************/
|
|
#define IPMACSEC_BUF_APPEND(buf,ptr,len) (void)ipmacsec_buf_append(buf,ptr,len)
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_VERIFY - MACRO used to verify if a buffer container is valid and has allocated data
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_VERIFY(buf)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: pointer to the ipmacsec_buffer container to verify.
|
|
* \ie
|
|
* DESCRIPTION
|
|
* Verify if a buffer container is valid and has allocated data
|
|
* RETURNS:
|
|
* TRUE if the buffer container has allocated data and is valid, FALSE otherwise.
|
|
*****************************************************************************/
|
|
#ifdef IP_DEBUG
|
|
#define IPMACSEC_BUF_VERIFY(buf) \
|
|
((buf) && (buf)->ptr && (buf)->alloc_size && ((buf)->size <= (buf)->alloc_size))
|
|
#else
|
|
#define IPMACSEC_BUF_VERIFY(buf) \
|
|
((buf)->ptr && (buf)->alloc_size && ((buf)->size <= (buf)->alloc_size))
|
|
#endif
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_HEAD - MACRO used to retrieve a pointer to the start of the data buffer
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_HEAD(buf)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: pointer to an ipmacsec_buffer container.
|
|
* \ie
|
|
* DESCRIPTION
|
|
* Retrieve a pointer to the start of the data buffer
|
|
* RETURNS:
|
|
* A pointer to the start of the data buffer if any is allocated,
|
|
* otherwise NULL if the buffer container is invalid or there is no allocated data buffer.
|
|
*****************************************************************************/
|
|
#define IPMACSEC_BUF_HEAD(buf) (IPMACSEC_BUF_VERIFY(buf) ? (buf)->ptr : IP_NULL)
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_TAIL - MACRO used to retrieve a pointer to the data buffer tail
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_TAIL(buf)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: pointer to an ipmacsec_buffer container.
|
|
* \ie
|
|
* DESCRIPTION
|
|
* Retrieve a pointer to the data buffer tail
|
|
* RETURNS:
|
|
* A pointer to the tail (remaining buffer data) if any,
|
|
* otherwise NULL if the buffer container is invalid or there is no remaining data buffer space.
|
|
*****************************************************************************/
|
|
#define IPMACSEC_BUF_TAIL(buf) \
|
|
(IPMACSEC_BUF_VERIFY(buf) && ((buf)->size < (buf)->alloc_size) ? ((buf)->ptr+(buf)->size) : IP_NULL)
|
|
|
|
/*****************************************************************************
|
|
* IPMACSEC_BUF_REM - MACRO used to retrieve the number of remaining data bytes
|
|
* SYNOPSIS
|
|
* IPMACSEC_BUF_REM(buf)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: pointer to an ipmacsec_buffer container.
|
|
* \ie
|
|
* DESCRIPTION
|
|
* Retrieve the number of remaining data bytes
|
|
* RETURNS:
|
|
* The number of remaining availble bytes in the data buffer (for append operations),
|
|
* otherwise 0 if the buffer container is invalid or there is no remaining data buffer space.
|
|
*****************************************************************************/
|
|
#define IPMACSEC_BUF_REM(buf) \
|
|
(IPMACSEC_BUF_VERIFY(buf) ? ((buf)->alloc_size - (buf)->size) : 0)
|
|
|
|
/* Time related manipulation macros:
|
|
* ===============================
|
|
* See Description section for details and examples.
|
|
*/
|
|
#define IPMACSEC_TIMEBUF(tbuf) char *tbuf[30]
|
|
#ifdef IPCOM_USE_TIME
|
|
#define IPMACSEC_STRFTIME(tbuf, tm) \
|
|
{ \
|
|
struct Ip_tm iptm; \
|
|
ipcom_localtime_r(&tm, &iptm); \
|
|
ipcom_strftime((char *)tbuf, 30, "%b %d %H:%M:%S", &iptm); \
|
|
}
|
|
#else
|
|
#define IPMACSEC_STRFTIME(tm) ipcom_strcpy(buf, "Time not available")
|
|
#endif
|
|
|
|
/* Validation macros:
|
|
* =================
|
|
* See Description section for details.
|
|
*/
|
|
#define IPMACSEC_ENABLE_FLAG_VALID(enf) \
|
|
(((enf)==IPMACSEC_ENABLEFLAG_IGNORE) || ((enf)==IPMACSEC_ENABLEFLAG_ON) || ((enf)==IPMACSEC_ENABLEFLAG_OFF))
|
|
|
|
#define IPMACSEC_CONFIDENTIALITY_VALID(conf) \
|
|
(((conf) == IPMACSEC_CONFIDENTIALITY_UNSPECIFIED) || \
|
|
((conf) == IPMACSEC_CONFIDENTIALITY_ON) || \
|
|
((conf) == IPMACSEC_CONFIDENTIALITY_OFF))
|
|
|
|
#define IPMACSEC_VALIDATEFRAMES_VALID(val) \
|
|
(((val) > __IPMACSEC_SECY_VALIDATEFRAMES_INVALID) && ((val) < __IPMACSEC_SECY_VALIDATEFRAMES_MAX))
|
|
|
|
#define IPMACSEC_SECY_VERIFY_CONFIDENTIALITY_OFFSET(confidentialityOffset) \
|
|
((confidentialityOffset == 0) || (confidentialityOffset == 30) || (confidentialityOffset == 50))
|
|
|
|
#define IPMACSEC_SECY_VERIFY_CIPHER_SUITE_INDEX(idx) \
|
|
(((Ip_u32)(idx) > (Ip_u32)__IPMACSEC_CIPHERSUITE_INVALID) && ((Ip_u32)(idx) < (Ip_u32)__IPMACSEC_CIPHERSUITE_MAX))
|
|
|
|
#define IPMACSEC_INVALID_SCI(sci) (*(Ip_u64 *)(sci) == 0xFFFFFFFFFFFFFFFFULL)
|
|
|
|
#define IPMACSEC_INVALID_AN(an) ((an) >= IPMACSEC_MAX_SA)
|
|
|
|
/* Common macros:
|
|
* =============
|
|
* See Description section for details .
|
|
*/
|
|
#define IPMACSEC_INVALIDATE_SCI(sci) (void)ipcom_memset((Ip_u8*)(sci), 0xFF, IPMACSEC_SCI_LEN)
|
|
#define IPMACSEC_COPY_SCI(dest,src) (void)ipcom_memcpy((dest),(src),IPMACSEC_SCI_LEN)
|
|
#define IPMACSEC_SCI_MATCH(sci1,sci2) (ipcom_memcmp((sci1),(sci2),IPMACSEC_SCI_LEN) == 0)
|
|
#define IPMACSEC_COPY_CIPHER_SUITE_ID(dest,src) (void)ipcom_memcpy((dest),(src),IPMACSEC_CIPHER_SUITE_ID_LEN)
|
|
#define IPMACSEC_BOOL_STRING(boolval) ((boolval) ? "TRUE" : "FALSE")
|
|
#define IPMACSEC_DIR_STRING(dir) (((dir) == IPMACSEC_TX) ? "TX" :" RX")
|
|
|
|
/* Common definitions used in printf/log routines:
|
|
* ==============================================
|
|
* See ipmacsec_lmi.c for usage examples.
|
|
*/
|
|
#define IPMACSEC_DISPLAY_BUF_LEN 256
|
|
#define IPMACSEC_SCI_STRING "%.2x-%.2x-%.2x-%.2x-%.2x-%.2x-%.2x-%.2x"
|
|
#define IPMACSEC_SCI_OCTETS(sci) (sci)[0],(sci)[1],(sci)[2],(sci)[3],(sci)[4],(sci)[5],(sci)[6],(sci)[7]
|
|
#define IPMACSEC_CIPHER_SUITE_ID_STRING "%.2x-%.2x-%.2x-%.2x-%.2x-%.2x-%.2x-%.2x"
|
|
#define IPMACSEC_CIPHER_SUITE_ID_OCTETS(csi) (csi)[0],(csi)[1],(csi)[2],(csi)[3],(csi)[4],(csi)[5],(csi)[6],(csi)[7]
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 5 TYPES
|
|
****************************************************************************
|
|
*/
|
|
|
|
typedef Ip_u64 Ipmacsec_secy_counter64;
|
|
typedef Ip_time_t Ipmacsec_time;
|
|
|
|
/* Layer Management Error Codes.
|
|
* ============================
|
|
* (Make sure ipmacsec_lmi_error_name() is also updated for each newly added Ipmacsec_lmi_error value)
|
|
*/
|
|
typedef enum {
|
|
IPMACSEC_LMIERR_NONE = 0, /* No error */
|
|
IPMACSEC_LMIERR_UNSPECIFIED_ERROR = -1,
|
|
IPMACSEC_LMIERR_ALLOC_FAILED = -2,
|
|
IPMACSEC_LMIERR_NETLINK_MSG_ERROR = -3,
|
|
IPMACSEC_LMIERR_NETLINK_PARAM_ERROR = -4,
|
|
IPMACSEC_LMIERR_NETLINK_OPEN_ERROR = -5,
|
|
IPMACSEC_LMIERR_NETLINK_REG_ERROR = -6,
|
|
IPMACSEC_LMIERR_NETLINK_REQUEST_ERROR = -7,
|
|
IPMACSEC_LMIERR_NETLINK_RESPONSE_ERROR = -8,
|
|
IPMACSEC_LMIERR_NETLINK_LOOP_ERROR = -9,
|
|
IPMACSEC_LMIERR_INVALID_REQUEST = -10,
|
|
IPMACSEC_LMIERR_INVALID_PID = -11,
|
|
IPMACSEC_LMIERR_INVALID_PARAMETER = -12,
|
|
IPMACSEC_LMIERR_SECY_DOESNOT_EXIST = -13,
|
|
IPMACSEC_LMIERR_CIPHER_SUITE_NOT_SUPPORTED = -14,
|
|
IPMACSEC_LMIERR_NOT_SUPPORTED = -15,
|
|
IPMACSEC_LMIERR_HANDLE_CREATE_FAILED = -16,
|
|
IPMACSEC_LMIERR_INVALID_PROFILE = -17,
|
|
IPMACSEC_LMIERR_CMD_NOT_FOUND = -18,
|
|
IPMACSEC_LMIERR_INVALID_CMD_SYNTAX = -19,
|
|
IPMACSEC_LMIERR_SECY_CMD_ERROR = -20
|
|
} Ipmacsec_lmi_error;
|
|
|
|
/* Indices for Cipher Suites supported by our MACsec implementation */
|
|
typedef enum {
|
|
__IPMACSEC_CIPHERSUITE_INVALID = 0, /* DO NOT MODIFY THIS. THIS MUST ALWAYS BE 1st */
|
|
IPMACSEC_CIPHERSUITE_GCM_AES_128 = 1,
|
|
|
|
#ifdef IPMACSEC_CRYPTO_ALLOW_NULL_CIPHER
|
|
/* IPMACSEC_CRYPTO_ALLOW_NULL_CIPHER should only be defined for debugging and development/unit testing
|
|
* since a NULL cipher does not meet the requirements set forth by 802.1AE.
|
|
*/
|
|
IPMACSEC_CIPHERSUITE_NULL_CIPHER_128,
|
|
#endif
|
|
__IPMACSEC_CIPHERSUITE_MAX /* DO NOT MODIFY THIS. MUST BE LAST */
|
|
} Ipmacsec_cipher_suite_index;
|
|
|
|
/* MACsec Cipher Suite descriptor structure. It specifies the cipher suite properties */
|
|
typedef struct Ipmacsec_ciphersuite_descriptor_struct {
|
|
char name[IPMACSEC_CIPHER_SUITE_NAME_LEN]; /* Cipher Suite Name (NULL terminated)*/
|
|
Ip_u8 id[IPMACSEC_CIPHER_SUITE_ID_LEN]; /* Cipher Suite Identifier */
|
|
Ipmacsec_cipher_suite_index index; /* Cipher Suite selector index */
|
|
Ip_bool integrityProtection; /* Supports Integrity with or without Confidentiality if set, otherwise no intergrity support */
|
|
Ip_bool confidentialityProtection; /* If set, supports Confidentiality (with Integrity if integrityProtection is set) */
|
|
Ip_bool offsetConfidentiality; /* A selectable offset for Confidentiality can be provided */
|
|
Ip_bool changesDataLength; /* If set, it changes the Data length when crypto operations are applied */
|
|
Ip_bool mandatory; /* Indicates whether this is a mandatory cipher suite for MACsec */
|
|
Ip_u32 key_bits; /* supportted Key size (in bits) */
|
|
Ip_u32 icv_bits; /* supportted ICV size (in bits) */
|
|
Ip_u64 min_iv_bits; /* minimum supportted IV size (in bits) */
|
|
Ip_u64 max_iv_bits; /* maximum supportted IV size (in bits) */
|
|
} Ipmacsec_ciphersuite_descriptor;
|
|
|
|
/* IPMACSEC Direction enum typdef */
|
|
typedef enum {
|
|
IPMACSEC_TX,
|
|
IPMACSEC_RX
|
|
} Ipmacsec_dir;
|
|
|
|
/* IPMACSEC key Type enum typdef.
|
|
* Note that this is a bitmap value, thus an Ipmacsec_keytype may be an OR of more than one value */
|
|
typedef enum {
|
|
IPMACSEC_KEYTYPE_NONE = 0x00,
|
|
IPMACSEC_KEYTYPE_TRANSMIT = 0x01,
|
|
IPMACSEC_KEYTYPE_RECEIVE = 0x02
|
|
} Ipmacsec_keytype;
|
|
|
|
/* Enum type for the IPMACSEC Enable control Flag values */
|
|
typedef enum {
|
|
IPMACSEC_ENABLEFLAG_IGNORE = 0, /* Do not enable or disable */
|
|
IPMACSEC_ENABLEFLAG_ON = 1, /* ENABLE */
|
|
IPMACSEC_ENABLEFLAG_OFF = 2 /* DISABLE */
|
|
} Ipmacsec_enable_flag;
|
|
|
|
/* Enum type for IPMACSEC Confidentiality setting */
|
|
typedef enum {
|
|
IPMACSEC_CONFIDENTIALITY_UNSPECIFIED = 0, /* Used to indicate that the system default should be used */
|
|
IPMACSEC_CONFIDENTIALITY_INVALID = 1, /* This value is Reserved and should never be used */
|
|
IPMACSEC_CONFIDENTIALITY_ON = 2, /* Used to indicate that confidentiality is ON */
|
|
IPMACSEC_CONFIDENTIALITY_OFF = 3 /* Used to indicate that confidentiality is OFF */
|
|
} Ipmacsec_confidentiality;
|
|
|
|
/* Enum type for IPMACSEC ValidateFrames control field */
|
|
typedef enum {
|
|
__IPMACSEC_SECY_VALIDATEFRAMES_INVALID = 0,
|
|
|
|
IPMACSEC_SECY_VALIDATEFRAMES_DISABLED = 1,
|
|
IPMACSEC_SECY_VALIDATEFRAMES_CHECK = 2,
|
|
IPMACSEC_SECY_VALIDATEFRAMES_STRICT = 3,
|
|
IPMACSEC_SECY_VALIDATEFRAMES_DEFAULT = IPMACSEC_SECY_VALIDATEFRAMES_STRICT,
|
|
|
|
__IPMACSEC_SECY_VALIDATEFRAMES_MAX /* MUST BE LAST */
|
|
} Ipmacsec_validateFrames_type;
|
|
|
|
|
|
/* IPMACsec Key Identifier (KI) */
|
|
typedef union {
|
|
Ip_u8 octet[8];
|
|
Ip_u64 val;
|
|
} Ipmacsec_secy_key_id;
|
|
|
|
/* IPMACsec Key Descriptor for installing keys and for retrieving key info.
|
|
* (When used as a MACsec command param when installing keys, it is followed by "key_size" octets of binary keying material)
|
|
*/
|
|
typedef struct Ipmacsec_secy_key_descriptor_struct {
|
|
Ipmacsec_secy_key_id key_id; /* unique identifier assigned by KaY or management */
|
|
Ipmacsec_time created_time; /* Set by SecY. Read Only value by management (ignored in MACsec command requests) */
|
|
Ip_bool inUse; /* Indicates that the key is currently in use by an SA.
|
|
* Set by SecY. Read Only value by management (ignored in MACsec command requests) */
|
|
Ipmacsec_keytype key_type; /* What a key can be used for: TX, RX or both */
|
|
Ip_u32 key_size; /* size of key in octets */
|
|
} Ipmacsec_secy_key_descriptor;
|
|
|
|
/* IPMACsec SC Info struct for retrieved SC status (both TX and RX SCs) (10.7.12, 10.7.20) */
|
|
typedef struct Ipmacsec_secy_sc_info_struct {
|
|
Ip_u8 sci[IPMACSEC_SCI_LEN];
|
|
Ipmacsec_time createdTime, startedTime, stoppedTime;
|
|
Ipmacsec_dir dir; /* SC direction. */
|
|
union {
|
|
struct {
|
|
Ip_bool transmitting; /* transmitting status for TX SC */
|
|
Ip_u8 encodingSA; /* Applies to Tx SC ONLY. (10.5.1) */
|
|
Ip_u8 encipheringSA; /* Applies to Tx SC ONLY. (10.5.1) */
|
|
} tx; /* used for TX SCs */
|
|
struct {
|
|
Ip_bool receiving; /* receiving status for RX SC */
|
|
} rx; /* used for RX SCs */
|
|
} status;
|
|
} Ipmacsec_secy_sc_info;
|
|
|
|
/* SA reference provided by KaY or network management */
|
|
typedef Ip_u32 Ipmacsec_secy_sa_ref;
|
|
|
|
/* IPMACsec SA Descriptor for SA creation/deletion/control or
|
|
* requesting/retrieving SA status (both TX and RX SAs)
|
|
* (10.7.13-15, 10.7.21-3) */
|
|
typedef struct Ipmacsec_secy_sa_descriptor_struct {
|
|
Ip_u8 sci[IPMACSEC_SCI_LEN]; /* SCI of the corresponding SC. Mandatory for create/delete/control/status-request;
|
|
* set in status-response. */
|
|
Ip_u8 an; /* SA Assciation Number. Mandatory for create/delete/control/status-request; set in status-response. */
|
|
Ipmacsec_dir dir; /* SA direction. */
|
|
Ipmacsec_secy_sa_ref ref; /* A management specific reference (10.7.21).
|
|
* Mandatory for create/delete/control (must match exiting ref for SA being deleted/controlled);
|
|
* Set to 0 if a reference is not desired.
|
|
* Ignored for status-request; set in status-response. */
|
|
Ipmacsec_secy_key_id key_id; /* Key Identifier for SAK associated with this SA.
|
|
* Mandatory for create; Ignored for delete/control/status-request; set in status-response. */
|
|
} Ipmacsec_secy_sa_descriptor;
|
|
|
|
/* IPMACsec SA Information used for SA creation and supplied in status-response (both TX and RX SAs) */
|
|
typedef struct Ipmacsec_secy_sa_info_struct {
|
|
union {
|
|
struct {
|
|
Ip_u32 nextPN;
|
|
Ipmacsec_confidentiality confidentiality; /* Enables encryption if confidentiality is on. */
|
|
} tx; /* used for TX SAs (10.7.21-22) */
|
|
struct {
|
|
Ip_u32 nextPN;
|
|
Ip_u32 lowestPN; /* Applies for Rx SA only */
|
|
} rx; /* used for RX SAs (10.7.13-14) */
|
|
} config; /* Optional for create; set in status-response. */
|
|
Ip_bool inUse; /* Ignored for requests; set in status-response. (10.7.13-14, 10.7.21-22) */
|
|
Ipmacsec_time createdTime, startedTime, stoppedTime; /* Ignored for requests; set in status-response. (10.7.13-14, 10.7.21-22)*/
|
|
} Ipmacsec_secy_sa_info;
|
|
|
|
/* SecY SA Control Information (used for TX/RX SAs by setting the appropriate fields) */
|
|
typedef union {
|
|
struct {
|
|
Ipmacsec_enable_flag enableTx; /* set to IPMACSEC_ENABLEFLAG_IGNORE to avoid enabling/disabling TX SA */
|
|
} tx; /* used for TX SAs (10.7.23) */
|
|
struct {
|
|
Ipmacsec_enable_flag enableRx; /* set to IPMACSEC_ENABLEFLAG_IGNORE to avoid enabling/disabling RX SA */
|
|
Ip_u32 updtNextPN; /* Set to 0 to avoid updating NextPN value */
|
|
Ip_u32 updtLowestPN; /* Set to 0 to avoid updating lowestPN value */
|
|
Ip_u32 padding; /* Pad to 16-byte boundary for some 64-bit compilers that handle padding/packing differently */
|
|
} rx; /* used for RX SAs (10.7.15) */
|
|
} Ipmacsec_secy_sa_ctrl;
|
|
|
|
#ifdef IPMACSEC_USE_STATS
|
|
/* SecY Statistics structure */
|
|
typedef struct ipmacsec_secy_stats_struct {
|
|
/* Validation stats */
|
|
Ipmacsec_secy_counter64 InPktsUntagged, InPktsNoTag, InPktsBadTag, InPktsUnknownSCI, InPktsNoSCI, InPktsOverrun;
|
|
Ipmacsec_secy_counter64 InOctetsValidated, InOctetsDecrypted;
|
|
/* Generation stats */
|
|
Ipmacsec_secy_counter64 OutPktsUntagged, OutPktsTooLong;
|
|
Ipmacsec_secy_counter64 OutOctetsProtected, OutOctetsEncrypted;
|
|
} Ipmacsec_secy_stats;
|
|
|
|
/* Union representing SecY SA statistics. Updated/Accessed based on whether SA is a TX or RX SA */
|
|
typedef union {
|
|
struct {
|
|
Ipmacsec_secy_counter64 OutPktsProtected, OutPktsEncrypted;
|
|
} tx; /* stats for TX SA */
|
|
struct {
|
|
Ipmacsec_secy_counter64 InPktsOK,
|
|
InPktsInvalid, InPktsNotValid,InPktsNotUsingSA, InPktsUnusedSA;
|
|
} rx; /* stats for RX SA */
|
|
} Ipmacsec_secy_sa_stats;
|
|
|
|
/* Union representing SecY SC statistics. Updated/Accessed based on whether SC is a TX or RX SC */
|
|
typedef struct {
|
|
struct {
|
|
Ipmacsec_secy_counter64 InPktsUnchecked, InPktsDelayed, InPktsLate;
|
|
} in; /* stats for RX SC */
|
|
Ipmacsec_secy_sa_stats aggr; /* These represent aggregate stats all the SC's SAs
|
|
* including previously deleted SAs (10.7.9, 10.7.18) */
|
|
} Ipmacsec_secy_sc_stats;
|
|
#endif
|
|
|
|
/* SecY Structure. Used by internal ipnet/ipmacsec modules ONLY. NOT FOR EXTERNAL PUBLIC API USE */
|
|
typedef struct Ipnet_secy_struct {
|
|
struct Ipnet_netif_struct *netif; /* Link back to the netif for this SecY */
|
|
Ipnet_link_input input; /* SecY Input handler */
|
|
Ipnet_link_raw_output output; /* SecY Output handler */
|
|
int (* ioctl)(struct Ipnet_netif_struct *netif, Ip_u32 request, void *data); /* SecY Ioctl handler */
|
|
struct {
|
|
Ip_u8 sci[IPMACSEC_SCI_LEN]; /* SecY TX SCI */
|
|
Ip_u8 cipher_suite_id[8]; /* Identifier of SecY current cipher suite */
|
|
Ipmacsec_cipher_suite_index cipher_suite_index; /* Index of SecY current cipher suite */
|
|
Ip_u16 confidentialityOffset; /* # of initial octets of each MSDU without confidentiality protection (0, 30, or 50)*/
|
|
Ip_u16 maxRxSCs; /* Set by SecY. Read Only value for others. MUST be <= IPMACSEC_MAX_RX_SC */
|
|
Ip_u16 maxRxKeys; /* Set by SecY. Read Only value for others. MUST be <= IPMACSEC_MAX_SA */
|
|
Ip_u16 maxTxKeys; /* Set by SecY. Read Only value for others. MUST be <= IPMACSEC_MAX_SA */
|
|
Ip_u32 pn_threshold; /* Threshold used for sending notification for PN near exhaustion of SAs */
|
|
Ip_bool info_notify; /* Enable/disable informational notifications for this SecY */
|
|
} config; /* Can be set via LMI API. Can be retrieved via LMI API */
|
|
struct {
|
|
Ip_u16 numActiveRxSCs; /* Current # of active Rx SCs, i.e. SCs with SAs enabled for reception (must be <= maxRxSCs) */
|
|
Ip_u16 numCreatedRxSCs; /* Current # of all created Rx SCs MUST be <= maxRxSCs */
|
|
} oper; /* Set internally by SecY ONLY. Can be retrieved via LMI API */
|
|
struct {
|
|
Ip_bool enabled;
|
|
|
|
/* Generation */
|
|
Ip_bool protectFrames;
|
|
Ip_bool alwaysIncludeSCI;
|
|
Ip_bool useES;
|
|
Ip_bool useSCB;
|
|
|
|
/* Validation */
|
|
|
|
/* Possible values for the SecY "validateFrames" control variable */
|
|
Ipmacsec_validateFrames_type validateFrames;
|
|
Ip_bool replayProtect;
|
|
Ip_u32 replayWindow;
|
|
} ctrl; /* Can be set via LMI API or using global sysvar values. Can be retrieved via LMI API */
|
|
#ifdef IPMACSEC_USE_STATS
|
|
Ipmacsec_secy_stats stats; /* SecY statistics. Updated internally by SecY ONLY. Can be retrieved via LMI API */
|
|
#endif
|
|
Ipnet_portif controlled_port, uncontrolled_port; /* Controlled and Uncontrolled Port structure used internally by ipnet/ipmacsec
|
|
* Port statistics are updated internally by SecY and can be retrieved via LMI API */
|
|
struct {
|
|
Ip_u32 nseq; /* Sequence number used for notifications*/
|
|
Ip_u32 rx_sc_iter; /* Receive SC Iterator */
|
|
struct Ipmacsec_secy_sc_struct *rx_sc; /* Pointer to RX SC.
|
|
* (To be replaced with a hash when more than 1 RX SC is supported in future releases) */
|
|
struct Ipmacsec_secy_sc_struct *tx_sc; /* Pointer to TX SC */
|
|
struct Ipmacsec_keydb_struct *keydb; /* Internal SecY Key Database. Used for both Tx and Rx keys */
|
|
} priv; /* Private members, used internally by SecY ONLY */
|
|
} Ipnet_secy;
|
|
|
|
/* IPMACSEC Buffer container:
|
|
* =========================
|
|
* See Description section for details.
|
|
*/
|
|
typedef struct Ipmacsec_buffer_struct {
|
|
Ip_u8 *ptr; /* Pointer to buffer data */
|
|
Ip_u32 size; /* Current size of buffer contents (in octets). */
|
|
Ip_u32 alloc_size; /* Allocated/max size of the buffer */
|
|
Ip_bool truncated; /* buffer contents were truncated */
|
|
Ip_bool donot_free; /* Do not free the buffer ptr when the free API is called since it was not allocated by the alloc API */
|
|
} Ipmacsec_buffer;
|
|
|
|
|
|
/* ----------------------------------------------------------------------------
|
|
SecY Setup Profiles
|
|
===================
|
|
Used to conveniently setup SecY instances (mainly for testing purposes)
|
|
by passing a Ipmacsec_secy_profile profile to ipmacsec_ut_setup_profile()
|
|
---------------------------------------------------------------------------- */
|
|
|
|
/* SAK Profile */
|
|
typedef struct {
|
|
Ip_u64 key_id_val;
|
|
Ip_u32 key_size; /* size of key in octets */
|
|
Ip_u8 *key_matrial; /* Pointer to the actual key material.
|
|
* Note that it is the responsibility of the profile owner to
|
|
* ensure the privacy (and thus clear) this keying material
|
|
* once setting up a profile is completed.
|
|
*/
|
|
} Ipmacsec_sak_profile;
|
|
|
|
/* TX/RX SA Profile */
|
|
typedef struct {
|
|
Ip_bool create; /* Create SA corresponding to this profile or not */
|
|
Ip_u8 an;
|
|
Ipmacsec_secy_sa_ref ref;
|
|
Ipmacsec_sak_profile *sak_profile; /* Pointer to SAK profile to use to create/install a key */
|
|
Ip_u32 nextPN;
|
|
Ipmacsec_confidentiality confidentiality; /*Applies to TX SA only */
|
|
Ip_u32 lowestPN; /* Applies to Rx SA only */
|
|
Ipmacsec_enable_flag enableTx; /*Applies to TX SA only */
|
|
Ipmacsec_enable_flag enableRx; /* Applies to Rx SA only */
|
|
} Ipmacsec_sa_profile;
|
|
|
|
/* TX/RX SC Profile */
|
|
typedef struct {
|
|
Ip_bool create; /* Create SC corresponding to this profile or not. Ignored for TX SCs */
|
|
char *sci_sysvar; /* The name of a sysvar variable that would contain the SCI value.
|
|
* Mandatory for RX SC profiles. Ignored for TX SC profiles.
|
|
*/
|
|
Ipmacsec_sa_profile sa_profile[IPMACSEC_MAX_SA];
|
|
} Ipmacsec_sc_profile;
|
|
|
|
/* Controlled Port Profile */
|
|
typedef struct {
|
|
Ip_bool ControlledPortEnabled;
|
|
Ip_portif_admin_ptp_mac_val adminPointToPointMAC;
|
|
} Ipmacsec_cp_profile;
|
|
|
|
/* SecY Profile:
|
|
* ------------
|
|
* Defines the various configurations to be used for a SecY interface.
|
|
*/
|
|
typedef struct {
|
|
char *sci_sysvar; /* The name of a sysvar variable that would contain the SecY SCI value (if any to be provided)
|
|
* Can be optionally absent or set to an invalid SCI value (all FFs) if useES is set
|
|
*/
|
|
Ipmacsec_cipher_suite_index cipher_suite_index;
|
|
|
|
Ip_bool protectFrames;
|
|
Ip_bool alwaysIncludeSCI;
|
|
Ip_bool useES;
|
|
Ip_bool useSCB;
|
|
|
|
Ipmacsec_validateFrames_type validateFrames;
|
|
Ip_bool replayProtect;
|
|
Ip_u32 replayWindow;
|
|
|
|
Ip_u16 confidentialityOffset;
|
|
|
|
Ip_u32 pn_threshold; /* value of 0 means no threshold is to be set */
|
|
Ip_bool info_notify;
|
|
|
|
Ipmacsec_cp_profile cp_profile;
|
|
|
|
Ipmacsec_sc_profile tx_sc_profile;
|
|
Ipmacsec_sc_profile rx_sc_profile[IPMACSEC_MAX_RX_SC];
|
|
} Ipmacsec_secy_profile;
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 6 FUNCTIONS
|
|
****************************************************************************
|
|
*/
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 6.1 IPNET API
|
|
*
|
|
* ONLY used internally by ipnet modules.
|
|
****************************************************************************
|
|
*/
|
|
/* The following APIs are to be used ONLY internally by ipnet modules */
|
|
IP_GLOBAL int ipmacsec_secy_init(struct Ipnet_netif_struct *netif);
|
|
IP_GLOBAL int ipmacsec_secy_config(struct Ipnet_netif_struct *netif);
|
|
IP_GLOBAL int ipmacsec_secy_delete(struct Ipnet_netif_struct *netif);
|
|
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 6.2 Buffer manipulation API
|
|
****************************************************************************
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_buf_alloc - Allocate a data buffer of specified size
|
|
* Allocates a data buffer and updates the fields of the specified buffer container.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A buffer container initialized with IPMACSEC_BUF_INIT() or one previously freed.
|
|
* Passing an already allocated buffer container will result in an error.
|
|
* \i <size>: Size of data to allocate (in bytes)
|
|
* \ie
|
|
* RETURNS:
|
|
* Pointer to allocated data if successful or NULL if failed.
|
|
* SEE ALSO:
|
|
* IPMACSEC_BUF_ALLOC()
|
|
*/
|
|
IP_PUBLIC Ip_u8 *ipmacsec_buf_alloc
|
|
(
|
|
Ipmacsec_buffer *buf,
|
|
Ip_u32 size
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_buf_set - Set the data buffer pointer and size
|
|
* Sets the data pointer and size for the specified buffer container
|
|
* and updates the applicable fields.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A buffer container initialized with IPMACSEC_BUF_INIT()
|
|
* or previously freed. Passing an already allocated buffer
|
|
* container will result in an error.
|
|
* \i <ptr>: Valid Pointer to a previously allocated data buffer to assign
|
|
* to the buf container (NOTE the original allocator stays as
|
|
* the owner of the data after this API is called and the
|
|
* data will not be freed when ipmacsec_buf_free() is called).
|
|
* \i <size>: size of data to assign to the buffer container.
|
|
* \ie
|
|
* RETURNS:
|
|
* Pointer to data if successful or NULL if failed.
|
|
*/
|
|
IP_PUBLIC Ip_u8 *ipmacsec_buf_set
|
|
(
|
|
Ipmacsec_buffer *buf,
|
|
Ip_u8 *ptr,
|
|
Ip_u32 size
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_buf_free - Free the data buffer
|
|
* Free the data buffer in the specified buffer container (if any) and reset
|
|
* the container fields.
|
|
* Note the data buffer is freed ONLY if previously allocated with
|
|
* ipmacsec_buf_alloc(). If ipmacsec_buf_set() was used instead
|
|
* the data buffer will not be freed but the buf container is cleared.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A valid buffer container
|
|
* \ie
|
|
* RETURNS:
|
|
* 0
|
|
*/
|
|
IP_PUBLIC int ipmacsec_buf_free
|
|
(
|
|
Ipmacsec_buffer *buf
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_buf_wipe - Clear the data buffer
|
|
* Clears the data buffer (if any is alloacted) and resets the buffer
|
|
* container dynamic fields (Does not free the allocated data buffer).
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A valid buffer container
|
|
* \ie
|
|
* RETURNS:
|
|
* a value >=0 (equal to the current data buffer size).
|
|
* SEE ALSO:
|
|
* IPMACSEC_BUF_WIPE()
|
|
*/
|
|
IP_PUBLIC int ipmacsec_buf_wipe
|
|
(
|
|
Ipmacsec_buffer *buf
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_buf_append - Append to a data buffer
|
|
*
|
|
* If a ptr is specified, appended data is copied, otherwise only the buffer
|
|
* container fields are updated accordingly.
|
|
* (buf->truncated is set if there is not enough space to append data).
|
|
*
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A valid allocated buffer container
|
|
* \i <ptr>: An optional pointer to the data to append
|
|
* \i <len>: Length of data to append
|
|
* \ie
|
|
* RETURNS:
|
|
* < 0 if failed to append the specified len,
|
|
* otherwise a value >= 0 (equal to remaining space in the buffer for future appends).
|
|
* SEE ALSO:
|
|
* IPMACSEC_BUF_APPEND()
|
|
*/
|
|
IP_PUBLIC int ipmacsec_buf_append
|
|
(
|
|
Ipmacsec_buffer *buf,
|
|
Ip_u8 *ptr,
|
|
Ip_u32 len
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_buf_ptr - Retrieve a pointer to data at specified offset
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <buf>: A valid buffer container
|
|
* \i <offset>: An offset for data
|
|
* \i <remlen>: Non NULL Pointer to a variable that will be updated with the
|
|
* length of remaining bytes from offset to end of buffer
|
|
* \ie
|
|
* RETURNS:
|
|
* A non NULL pointer to the data at the specified offset if the offset is within
|
|
* the buffer's data size range,
|
|
* IP_NULL otherwise (i.e. offset is beyond buffer data size boundary).
|
|
*/
|
|
IP_PUBLIC Ip_u8 *ipmacsec_buf_ptr
|
|
(
|
|
Ipmacsec_buffer *buf,
|
|
Ip_u32 offset,
|
|
Ip_u32 *remlen
|
|
);
|
|
|
|
/*
|
|
****************************************************************************
|
|
* 6.3 LMI API
|
|
*
|
|
* The following LMI APIs are Public APIs that can be used by KaY, network management,
|
|
* or other 3rd party software interfacing with the MACsec software.
|
|
****************************************************************************
|
|
*/
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_protocol_version - Retrieve the currently supported MACsec protocol version number
|
|
* PARAMETERS:
|
|
* None
|
|
* RETURNS:
|
|
* MACsec version number with value >=0, otherwise an lmi error code with value < 0
|
|
*****************************************************************************/
|
|
IP_PUBLIC int ipmacsec_lmi_protocol_version
|
|
(
|
|
void
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_handle_create - Create an LMI handle to be used when invoking LMI APIs
|
|
* Using an LMI handle improves performances and optimizes resource usage
|
|
* when multiple LMI APIs need to be invoked within the same context.
|
|
* NOTE: The returned handle MUST ONLY be used within the same context
|
|
* in which it was created, otherwise unexpected/incorrect behavior may occur.
|
|
* PARAMETERS:
|
|
* None
|
|
* RETURNS:
|
|
* IP_NULL upon failure, otherwise a non-Null IPMACSEC_LMI_HANDLE
|
|
*****************************************************************************/
|
|
IP_PUBLIC IPMACSEC_LMI_HANDLE ipmacsec_lmi_handle_create
|
|
(
|
|
void
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_handle_delete - Delete an LMI handle and free its associated resources
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: lmi handle to delete
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*****************************************************************************/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_handle_delete
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_exists - Query if a SecY instance exists
|
|
* A secY instance exists if the specified interface is attached and SecY initialized on it.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \ie
|
|
* RETURNS:
|
|
* IP_TRUE if the SecY exists,
|
|
* IP_FALSE if it doesn't exist or we could not retrieve that information.
|
|
*/
|
|
IP_PUBLIC Ip_bool ipmacsec_lmi_secy_exists
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_enable - Enable/Disable SecY interface
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <enable>: Enable parameter (IP_TRUE to enable, IP_FALSE to disable)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_enable
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool enable
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_is_enabled - Query if SecY is enabled on an interface
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <enabled>: Pointer to the enable parameter which will be updated upon
|
|
* successful return (set to IP_TRUE if enabled, or IP_FALSE if disabled)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (enabled is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_is_enabled
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *enabled
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_protectFrames - Set the SecY protectFrames value
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <protectFrames>: The protectFrames boolean value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_protectFrames
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool protectFrames
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_protectFrames - Get the current SecY protectFrames value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <protectFrames>: Pointer to the variable to contain the retrieved protectFrames value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (protectFrames is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_protectFrames
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *protectFrames
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_alwaysIncludeSCI - Set the SecY alwaysIncludeSCI value
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <alwaysIncludeSCI>: The alwaysIncludeSCI boolean value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_alwaysIncludeSCI
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool alwaysIncludeSCI
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_alwaysIncludeSCI - Get the current SecY alwaysIncludeSCI value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <alwaysIncludeSCI>: Pointer to the variable to contain the retrieved alwaysIncludeSCI value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (alwaysIncludeSCI is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_alwaysIncludeSCI
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *alwaysIncludeSCI
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_useES - Set the SecY useES value
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <useES>: The useES boolean value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_useES
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool useES
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_useES - Get the current SecY useES value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <useES>: Pointer to variable to contain the retrieved useES value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (useES is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_useES
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *useES
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_useSCB - Set the SecY useSCB value
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <useSCB>: The useSCB boolean value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_useSCB
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool useSCB
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_useSCB - Get the current SecY useSCB value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <useSCB>: Pointer to variable to contain the retrieved useSCB value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (useSCB is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_useSCB
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *useSCB
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_validateFrames - Set the SecY validateFrames value
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <validateFrames>: The validateFrames value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_validateFrames
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_validateFrames_type validateFrames
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_validateFrames - Get the current SecY validateFrames value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <validateFrames>: Pointer to variable to contain the retrieved validateFrames value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (validateFrames is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_validateFrames
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_validateFrames_type *validateFrames
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_replayProtect - Set the SecY replayProtect value
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <replayProtect>: The replayProtect boolean value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_replayProtect
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool replayProtect
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_replayProtect - Get the current SecY replayProtect value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <replayProtect>: Pointer to variable to contain the retrieved replayProtect value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (replayProtect is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_replayProtect
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *replayProtect
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_replayWindow - Set the SecY replayWindow value
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <replayWindow>: The replayWindow value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_replayWindow
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u32 replayWindow
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_replayWindow - Get the current SecY replayWindow value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <replayWindow>: Pointer to variable to contain the retrieved replayWindow value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (replayWindow is not updated in this case)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_replayWindow
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u32 *replayWindow
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_key_install - Install a MACsec SecY Transmit and/or Receive Key (SAK)
|
|
* Note that trying to install the same key more than once
|
|
* using the same key_id will result in a failure. If it is desired
|
|
* to change/add key_type properties, the key must be removed 1st then re-installed.
|
|
* Also note that there are no checks to prevent 2 keys with different
|
|
* key_id values from using the same keying material. It is up to the
|
|
* caller to enforce such checks. It is highly recommended that
|
|
* keying material not be reused with different keys to ensure proper security protection.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name used to install the key.
|
|
* \i <key_desc>: Pointer to a valid key descriptor containing
|
|
* a unique key_id (unique per SecY), a valid key_size and a valid key_type with either
|
|
* IPMACSEC_KEYTYPE_TRANSMIT, or IPMACSEC_KEYTYPE_RECEIVE set, or both.
|
|
* \i <key>: A valid pointer to a buffer containing the binary key material.
|
|
* NOTE that it is the caller's responsibility to clear the contents
|
|
* of this buffer (for security purposes) once this function returns.
|
|
* This function will only clear other temporary buffer containers
|
|
* it uses to copy the key.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_key_install
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_key_descriptor *key_desc,
|
|
Ip_u8 *key
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_key_remove - Remove a key (SAK) from the MACsec SecY key database
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name used to remove the key.
|
|
* \i <key_desc>: Pointer to a valid key descriptor containing the key_id for the
|
|
* key to remove. The rest of the key descriptor fields are irrelevant.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_key_remove
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_key_descriptor *key_desc
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_key_purge - Purge all SecY keys that are not in use by SAs
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name used to purge the keys.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_key_purge
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_key_info - Retrieve SecY key information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name used to retrieve the key info.
|
|
* \i <key_desc>: (optional) Pointer to a valid key descriptor containing the key_id
|
|
* for the key whose info to retrieve. The rest of the key descriptor fields are irrelevant.
|
|
* If NULL, then info is retrieved for all installed keys.
|
|
* \i <info>: Valid buffer pointer to contain the retrieved key information.
|
|
* It should be at least sizeof(Ipmacsec_secy_key_descriptor) long
|
|
* if retrieving a single key information (i.e. when key_desc != NULL).
|
|
* If retrieving all key info (i.e. when key_desc == NULL), then it
|
|
* should be N times sizeof(Ipmacsec_secy_key_descriptor),
|
|
* where N is the total number of installed keys for the SecY.
|
|
* If there isn't enough buffer space provided, the info will be truncated
|
|
* but no failure will occur due to truncation.
|
|
* Also in case of all key retrieval, no error is returned if no
|
|
* keys are available (but the info buffer will be empty).
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 upon error.
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_key_info
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_key_descriptor *key_desc,
|
|
Ipmacsec_buffer *info
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_sa_descriptor_init - Ipmacsec_secy_sa_descriptor initializer
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <sa_desc>: Valid pointer to a the Ipmacsec_secy_sa_descriptor to initialize
|
|
* \i <sci>: Pointer to SCI of the corresponding SC. For TX SC, this can be
|
|
* set to NULL (an all FF value will be filled in the Ipmacsec_secy_sa_descriptor sci field).
|
|
* \i <an>: valid SA Assciation Number
|
|
* \i <dir>: valid sa direction
|
|
* \i <ref>: (optional) SA reference (set it to 0 if no reference is desired).
|
|
* \i <key_id>: (Optional) Pointer to Key Identifier. If NULL is provided, then
|
|
* the key_id field in Ipmacsec_secy_sa_descriptor is set to 0.
|
|
* This should only be done for operations that do not require a
|
|
* valid key_id value in the Ipmacsec_secy_sa_descriptor.
|
|
* \ie
|
|
* RETURNS:
|
|
* sa_desc pointer upon success, IP_NULL on failure
|
|
*/
|
|
IP_PUBLIC Ipmacsec_secy_sa_descriptor *ipmacsec_lmi_secy_sa_descriptor_init
|
|
(
|
|
Ipmacsec_secy_sa_descriptor *sa_desc,
|
|
Ip_u8 *sci,
|
|
Ip_u8 an,
|
|
Ipmacsec_dir dir,
|
|
Ipmacsec_secy_sa_ref ref,
|
|
Ipmacsec_secy_key_id *key_id
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_rx_sa_info_init - RX Ipmacsec_secy_sa_info initializer
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <sa_info>: Valid pointer to the Ipmacsec_secy_sa_info to initialize
|
|
* \i <nextPN>: nextPN value (set to 0 if no PN value is being specified)
|
|
* \i <lowestPN>: lowestPN value (set to 0 if no PN value is being specified)
|
|
* \ie
|
|
* RETURNS:
|
|
* sa_info pointer upon success, IP_NULL on failure
|
|
*/
|
|
IP_PUBLIC Ipmacsec_secy_sa_info *ipmacsec_lmi_secy_rx_sa_info_init
|
|
(
|
|
Ipmacsec_secy_sa_info *sa_info,
|
|
Ip_u32 nextPN,
|
|
Ip_u32 lowestPN
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_tx_sa_info_init - TX Ipmacsec_secy_sa_info initializer
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <sa_info>: Valid pointer to the Ipmacsec_secy_sa_info to initialize
|
|
* \i <nextPN>: nextPN value (set to 0 if no PN value is being specified)
|
|
* \i <confidentiality>: confidentiality value (set to IPMACSEC_CONFIDENTIALITY_UNSPECIFIED
|
|
* if no confidentiality value is being specified)
|
|
* \ie
|
|
* RETURNS:
|
|
* sa_info pointer upon success, IP_NULL on failure
|
|
*/
|
|
IP_PUBLIC Ipmacsec_secy_sa_info *ipmacsec_lmi_secy_tx_sa_info_init
|
|
(
|
|
Ipmacsec_secy_sa_info *sa_info,
|
|
Ip_u32 nextPN,
|
|
Ipmacsec_confidentiality confidentiality
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_rx_sa_ctrl_init - RX Ipmacsec_secy_sa_ctrl initializer
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <sa_ctrl>: Valid pointer to the Ipmacsec_secy_sa_ctrl to initialize
|
|
* \i <enableRx>: enableRx value (set to IPMACSEC_ENABLEFLAG_IGNORE if
|
|
* no enableRx value is being specified)
|
|
* \i <updtNextPN>: updtNextPN value (set to 0 if no PN value is being specified)
|
|
* \i <updtLowestPN>: updtLowestPN value (set to 0 if no PN value is being specified)
|
|
* \ie
|
|
* RETURNS:
|
|
* sa_ctrl pointer upon success, IP_NULL on failure
|
|
*/
|
|
IP_PUBLIC Ipmacsec_secy_sa_ctrl *ipmacsec_lmi_secy_rx_sa_ctrl_init
|
|
(
|
|
Ipmacsec_secy_sa_ctrl *sa_ctrl,
|
|
Ipmacsec_enable_flag enableRx,
|
|
Ip_u32 updtNextPN,
|
|
Ip_u32 updtLowestPN
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_tx_sa_ctrl_init - TX Ipmacsec_secy_sa_ctrl initializer
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <sa_ctrl>: Valid pointer to the Ipmacsec_secy_sa_ctrl to initialize
|
|
* \i <enableTx>: enableTx value (set to IPMACSEC_ENABLEFLAG_IGNORE if
|
|
* no enableTx value is being specified)
|
|
* \ie
|
|
* RETURNS:
|
|
* sa_ctrl pointer upon success, IP_NULL on failure
|
|
*/
|
|
IP_PUBLIC Ipmacsec_secy_sa_ctrl *ipmacsec_lmi_secy_tx_sa_ctrl_init
|
|
(
|
|
Ipmacsec_secy_sa_ctrl *sa_ctrl,
|
|
Ipmacsec_enable_flag enableTx
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_create_rx_sc - Create an RX SC with the specified SCI
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: Valid Pointer to SCI for Rx SC to be created
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_create_rx_sc
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 *sci
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_delete_rx_sc - Delete an RX SC with the specified SCI
|
|
* Also deletes the associated RX SAs.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: Valid Pointer to SCI for Rx SC to be deleted
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_delete_rx_sc
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 *sci
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_rx_sc_status - Retrieve the specified Rx SC status information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: Pointer to SCI for Rx SC whose info is to be retrieved
|
|
* If NULL, all RX SC info will be retrieved.
|
|
* \i <info>: Valid buffer pointer to contain the retrieved SC info.
|
|
* Should be at least sizeof(Ipmacsec_secy_sc_info) long
|
|
* if retrieving a single Rx SC information (i.e. if sci != NULL).
|
|
* If retrieving all Rx SC info (i.e. if sci == NULL), then it
|
|
* should be N times sizeof(Ipmacsec_secy_sc_info), where N is
|
|
* the number of created Rx SCs.
|
|
* If there isn't enough buffer space provided, the info will be truncated
|
|
* but no failure will occur due to truncation.
|
|
* Also in case of all Rx SC retrieval, no error is returned if no
|
|
* Rx SCs are available (but the info buffer will be empty).
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_rx_sc_status
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 *sci,
|
|
Ipmacsec_buffer *info
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_create_tx_sc - Create the TX SC
|
|
* To be invoked before enabling the SecY but after setting its
|
|
* SCI using ipmacsec_lmi_secy_set_tx_sci() if useES is not set.
|
|
* It is not necessary to call this API after SecY is enabled
|
|
* successfully, since the TX SC is created automatically when
|
|
* a SecY is enabled. However calling it after the TX SC was
|
|
* created does not yield any errors.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_create_tx_sc
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_delete_tx_sc - Delete the TX SC
|
|
* Can be invoked before disabling the SecY.
|
|
* Since disabling the SecY automatically deletes the TX SC
|
|
* (and all other SCs and SecY members for that matter),
|
|
* invoking this API after a SecY is disabled will return an error.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_delete_tx_sc
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_tx_sc_status - Retrieve the Tx SC status information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sc_info>: Valid pointer to structure to which SC info is copied
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_tx_sc_status
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sc_info *sc_info
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_create_rx_sa - Create an RX SA
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_desc>: Valid pointer to a mandatory Ipmacsec_secy_sa_descriptor parameter
|
|
* that contains valid RX "sci", "an", and "key_id" for an already installed RX key
|
|
* and an optional "ref" field (set to 0 if none desired).
|
|
* \i <sa_info>: (Optional) Pointer to an Ipmacsec_secy_sa_info used to set the
|
|
* desired nextPN and/or lowestPN for the created SA.
|
|
* If NULL, default values of nextPN and lowestPN are used.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_create_rx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_descriptor *sa_desc,
|
|
Ipmacsec_secy_sa_info *sa_info
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_delete_rx_sa - Delete an RX SA
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_desc>: Valid pointer to a mandatory Ipmacsec_secy_sa_descriptor parameter
|
|
* that contains valid RX "sci", "an",
|
|
* and a "ref" field that matches the value used to create the SA
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_delete_rx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_descriptor *sa_desc
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_control_rx_sa - Update an RX SA's control field
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_desc>: Valid pointer to a mandatory Ipmacsec_secy_sa_descriptor parameter
|
|
* that contains valid RX "sci", "an",
|
|
* and a "ref" field that matches the value used to create the SA
|
|
* \i <sa_ctrl>: Valid pointer to a mandatory Ipmacsec_secy_sa_ctrl parameter
|
|
* that contains the rx fields to be updated
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_control_rx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_descriptor *sa_desc,
|
|
Ipmacsec_secy_sa_ctrl *sa_ctrl
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_rx_sa_status - Retrieve the specified Rx SA(s) status information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: Pointer to SCI for Rx SC corresponding to the RX SA
|
|
* whose info to be retrieved (Cannot be NULL).
|
|
* \i <an>: Association number for the RX SA.
|
|
* Must be <= maxRxKeys otherwise a failure will occur.
|
|
* If < 0, then info for all created RX SAs for
|
|
* the specified SC are retrieved.
|
|
* \i <ref>: SA reference. Ignored if an < 0, otherwise must match
|
|
* the existing SA reference for the SA info to be successfully
|
|
* retrieved.
|
|
* \i <info>: Valid buffer pointer to hold the retrieved SA info.
|
|
* Should be at least sizeof(Ipmacsec_secy_sa_info) long
|
|
* if retrieving a single Rx SA information (i.e. if an >= 0).
|
|
* If retrieving all Rx SA info (i.e. if an < 0), then it should be
|
|
* N times sizeof(Ipmacsec_secy_key_descriptor), where N is equal to maxRxKeys.
|
|
* If not enough buffer space is provided, the info will be truncated
|
|
* but no failure will occur due to the truncation.
|
|
* Also in case of all Rx SA retrieval, no error is returned if no
|
|
* Rx SAs are available (but the info buffer will be empty).
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (including an invalid RX sci)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_rx_sa_status
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 *sci,
|
|
int an,
|
|
Ip_u32 ref,
|
|
Ipmacsec_buffer *info
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_create_tx_sa - Create a TX SA
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_desc>: Valid pointer to a mandatory Ipmacsec_secy_sa_descriptor parameter
|
|
* that contains valid TX "an", and "key_id" for an already installed TX key
|
|
* and an optional "ref" field (set to 0 if none desired).
|
|
* \i <sa_info>: (Optional) Pointer to an Ipmacsec_secy_sa_info used to set the
|
|
* desired nextPN and/or confidentiality for the created SA.
|
|
* If NULL, default values of nextPN and confidentiality are used.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_create_tx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_descriptor *sa_desc,
|
|
Ipmacsec_secy_sa_info *sa_info
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_delete_tx_sa - Delete a TX SA
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_desc>: Valid pointer to a mandatory Ipmacsec_secy_sa_descriptor parameter
|
|
* that contains valid TX "an",
|
|
* and a "ref" field that matches the value used to create the SA
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_delete_tx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_descriptor *sa_desc
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_control_tx_sa - Update a TX SA's control field(s)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_desc>: Valid pointer to a mandatory Ipmacsec_secy_sa_descriptor parameter
|
|
* that contains valid "an" and a "ref" field that matches the value used to create the SA
|
|
* \i <sa_ctrl>: Valid pointer to a mandatory Ipmacsec_secy_sa_ctrl parameter
|
|
* that contains the tx fields to be updated
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_control_tx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_descriptor *sa_desc,
|
|
Ipmacsec_secy_sa_ctrl *sa_ctrl
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_enable_tx_sa - Enable/Disable an already created TX SA
|
|
* Enabling a new TX SA disables the current enabled TX SA (if any).
|
|
* This API is typically used when the current TX SA's PN is exhausted
|
|
* or near exhaustion (the latter case assures uninterrupted traffic
|
|
* flow if the receiving SecYs already have the corresponding RX SAs
|
|
* properly created and enabled).
|
|
* This API achieves the same objectives as using the
|
|
* ipmacsec_lmi_secy_control_tx_sa() but is more convenient.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <an>: Association Number for the TX SA to enable. Must correspond to a valid created TX SA.
|
|
* \i <ref>: SA reference. Must match the existing SA reference for the SA being enabled.
|
|
* \i <enable>: Set to IP_TRUE to enabled the SA, IP_FALSE to disable it.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
* SEE ALSO:
|
|
* ipmacsec_lmi_secy_control_tx_sa()
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_enable_tx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 an,
|
|
Ip_u32 ref,
|
|
Ip_bool enable
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_tx_sa_status - Retrieve the specified Tx SA(s) status information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <an>: Association number for the TX SA.
|
|
* Must be <= maxTxKeys otherwise a failure will occur.
|
|
* If < 0, then info for all created TX SAs are retrieved.
|
|
* \i <ref>: SA reference. Ignored if an < 0, otherwise must match
|
|
* the existing SA reference for the SA info to be successfully
|
|
* retrieved.
|
|
* \i <info>: Valid buffer pointer to contain the retrieved SA info.
|
|
* Should be at least sizeof(Ipmacsec_secy_sa_info) long
|
|
* if retrieving a single Tx SA information (i.e. if an >= 0).
|
|
* If retrieving all Tx SA info (i.e. if an < 0), then it should be
|
|
* N times sizeof(Ipmacsec_secy_sa_info), where N is equal to maxTxKeys.
|
|
* If not enough buffer space is provided, the info will be truncated
|
|
* but no failure will occur due to truncation.
|
|
* Also in case of all Tx SA retrieval, no error is returned if no
|
|
* Tx SAs are available (but the info buffer will be empty).
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_tx_sa_status
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
int an,
|
|
Ip_u32 ref,
|
|
Ipmacsec_buffer *info
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_tx_sci - Set the SCI value to be used by the TX SC when it gets created
|
|
* If an invalid SCI value is specified (All FFs) then this essentially
|
|
* clears the configured TX SCI value. If the TX SC is created without a
|
|
* valid SCI specified then one of two things will happen:
|
|
* - If useES is set, then the SCI is initialized using
|
|
* the interface MAC address and default port 00-01 if useSCB is not set
|
|
* or port 00-00 if useSCB is set. (A5(SCI); 8.2.1; 9.5)
|
|
* - Otherwise the TX SC create operation will fail.
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: pointer to an sci value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_tx_sci
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 *sci
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_tx_sci - Get the currently configured SecY Tx SCI value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: pointer to a variable to hold the retrieved sci value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (sci is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_tx_sci
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 *sci
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_confidentialityOffset - Set the confidentialityOffset value
|
|
* Set the confidentialityOffset value to be used by the crypto
|
|
* cipher suite when SecY gets enabled.
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <confidentialityOffset>: A valid confidentialityOffset value (0, 30 or 50).
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_confidentialityOffset
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u16 confidentialityOffset
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_confidentialityOffset - Get the currently configured SecY confidentialityOffset value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <confidentialityOffset>: pointer to a variable to hold the retrieved
|
|
* confidentialityOffset value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (confidentialityOffset is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_confidentialityOffset
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u16 *confidentialityOffset
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_cipher_suite_id_resolve - Resolve the Cipher Suite ID from a specified cipher_suite_index
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <cipher_suite_index>: cipher_suite_index value to resolve
|
|
* \i <cipher_suite_id>: pointer to variable to hold the resolved Cipher Suite ID
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_cipher_suite_id_resolve
|
|
(
|
|
IP_CONST Ipmacsec_cipher_suite_index cipher_suite_index,
|
|
Ip_u8 *cipher_suite_id
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_cipher_suite_index_resolve - Resolve the Cipher Suite Index from a specified cipher_suite_id
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <cipher_suite_id>: Cipher Suite ID value to resolve
|
|
* \i <cipher_suite_index>: pointer to variable to hold the resolved cipher_suite_index
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_cipher_suite_index_resolve
|
|
(
|
|
IP_CONST Ip_u8 *cipher_suite_id,
|
|
Ipmacsec_cipher_suite_index *cipher_suite_index
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_cipher_suite_name - Return the name of the specified Cipher Suite
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <cipher_suite_index>: index of Cipher Suite whose name to return
|
|
* \ie
|
|
* RETURNS:
|
|
* Pointer to string containing the Cipher Suite name (never null).
|
|
*/
|
|
IP_PUBLIC IP_CONST char *ipmacsec_lmi_cipher_suite_name
|
|
(
|
|
IP_CONST Ipmacsec_cipher_suite_index cipher_suite_index
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_cipher_suite - Set the cipher suite to be used when the SCs get created
|
|
* If an invalid or unsupported cipher_suite is specified,
|
|
* this operation will fail without setting a cipher suite.
|
|
* The default cipher suite would be used instead.
|
|
* This operation is only allowed when the SecY is disabled, and
|
|
* will return a failure without setting the value if the SecY is enabled.
|
|
* Also invoking this when SCs have already been created will
|
|
* result in failure of this operation without changing the value.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <cipher_suite_index>: A valid supported cipher_suite_index value.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_cipher_suite
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_cipher_suite_index cipher_suite_index
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_cipher_suite - Get the currently configured SecY cipher suite information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <cipher_suite_desc>: pointer to variable to hold retrieved cipher_suite information
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_cipher_suite
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_ciphersuite_descriptor *cipher_suite_desc
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_cipher_suite_info - Get the specified cipher suite information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <cipher_suite_index>: A valid supported cipher_suite_index value indicating
|
|
* the cipher suite whose info to retrieve.
|
|
* \i <cipher_suite_desc>: pointer to variable to hold retrieved cipher_suite information
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_cipher_suite_info
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
IP_CONST Ipmacsec_cipher_suite_index cipher_suite_index,
|
|
Ipmacsec_ciphersuite_descriptor *cipher_suite_desc
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_cipher_suite_info_list - Get the information for all the supported cipher suites
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <desc>: Valid buffer pointer to contain the retrieved cipher suite descriptor list.
|
|
* Should be N times sizeof(Ipmacsec_ciphersuite_descriptor),
|
|
* where N is equal to __IPMACSEC_CIPHERSUITE_MAX-1.
|
|
* If not enough buffer space is provided, the info will be truncated
|
|
* but no failure will occur due to truncation.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_cipher_suite_info_list
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_buffer *desc
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_maxRxSCs - Get the current SecY maxRxSCs value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <maxRxSCs>: pointer to variable to hold the retrieved maxRxSCs value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (maxRxSCs is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_maxRxSCs
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u16 *maxRxSCs
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_maxRxKeys - Get the current SecY maxRxKeys value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <maxRxKeys>: pointer to variable to hold the retrieved maxRxKeys value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (maxRxKeys is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_maxRxKeys
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u16 *maxRxKeys
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_maxTxKeys - Get the current SecY maxTxKeys value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <maxTxKeys>: pointer to variable to hold the retrieved maxTxKeys value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (maxTxKeys is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_maxTxKeys
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u16 *maxTxKeys
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_pn_threshold - Set the Packet Number threshold
|
|
* Set the PN threshold used by the SecY for sending notification
|
|
* for PN near exhaustion of SAs
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <threshold>: Threshold value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_pn_threshold
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u32 threshold
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_pn_threshold - Get the current SecY PN threshold value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <threshold>: pointer to variable to hold the retrieved threshold value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (threshold is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_pn_threshold
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u32 *threshold
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_info_notification - Turn SecY Information Notifications On/Off
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <on>: On/Off indication (IP_TRUE ==> on, IP_FALSE ==> off)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_info_notification
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool on
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_info_notification - Get the configured SecY Information Notification value
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <on>: variable to hold the retrieved On/Off value (IP_TRUE ==> on, IP_FALSE ==> off)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (on is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_info_notification
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *on
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_numActiveRxSCs - Get the number of currently active RX SCs for the specified SecY
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <numActiveRxSCs>: pointer to variable to hold the retrieved numActiveRxSCs value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (numActiveRxSCs is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_numActiveRxSCs
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u16 *numActiveRxSCs
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_numCreatedRxSCs - Get the number of currently created RX SCs for the specified SecY
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <numCreatedRxSCs>: pointer to variable to hold the retrieved numCreatedRxSCs value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (numCreatedRxSCs is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_numCreatedRxSCs
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u16 *numCreatedRxSCs
|
|
);
|
|
|
|
#ifdef IPMACSEC_USE_STATS
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_stats - Retrieve the SecY statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <secy_stats>: Valid pointer to Ipnet_secy_stats structure to hold the retrieved stats
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (secy_stats is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_stats *secy_stats
|
|
);
|
|
#endif
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_reset_stats - Reset the statistics for the SecY and for its Controlled Port
|
|
* This operation is only allowed when the SecY is disabled, and will return a
|
|
* failure without resetting the stats if the SecY is enabled.
|
|
* Note that SC/SA stats are automatically cleared upon disabling the
|
|
* SecY since all SCs/SAs are deleted when a SecY is disabled.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_reset_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_ControlledPortEnabled - Set the SecY ControlledPortEnabled control
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <cp_enabled>: The ControlledPortEnabled control value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_ControlledPortEnabled
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool cp_enabled
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_ControlledPortEnabled - Retrieve the SecY ControlledPortEnabled control
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <cp_enabled>: Pointer to variable to hold the retrieved ControlledPortEnabled control value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (cp_enabled is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_ControlledPortEnabled
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *cp_enabled
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_MAC_Enabled - Retrieve the SecY MAC_Enabled control of the Controlled or Uncontrolled Port
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <mac_enabled>: Pointer to variable to hold the retrieved MAC_Enabled control value
|
|
* \i <cp>: Set to TRUE for Controlled port, or FALSE for uncontrolled port
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (mac_enabled is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_MAC_Enabled
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *mac_enabled,
|
|
Ip_bool cp
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_MAC_Operational - Retrieve the SecY MAC_Operational control of the Controlled or Uncontrolled Port
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <mac_oper>: Pointer to variable to hold the retrieved MAC_Operational control value
|
|
* \i <cp>: Set to TRUE for Controlled port, or FALSE for uncontrolled port
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (mac_oper is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_MAC_Operational
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *mac_oper,
|
|
Ip_bool cp
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_operPointToPointMAC - Retrieve the SecY operPointToPointMAC control of the Controlled or Uncontrolled Port
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <oper_ptp_mac>: Pointer to variable to hold the retrieved operPointToPointMAC control value
|
|
* \i <cp>: Set to TRUE for Controlled port, or FALSE for uncontrolled port
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (oper_ptp_mac is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_operPointToPointMAC
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool *oper_ptp_mac,
|
|
Ip_bool cp
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_set_adminPointToPointMAC - Set the SecY adminPointToPointMAC control for the Controlled Port
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <admin_ptp_mac>: The adminPointToPointMAC control value to set
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_set_adminPointToPointMAC
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_portif_admin_ptp_mac_val admin_ptp_mac
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_adminPointToPointMAC - Retrieve the SecY adminPointToPointMAC control for the Controlled Port
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <admin_ptp_mac>: Pointer to variable to hold the retrieved adminPointToPointMAC control value
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (admin_ptp_mac is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_adminPointToPointMAC
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_portif_admin_ptp_mac_val *admin_ptp_mac
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_port_stats - Retrieve the SecY Contolled or Uncontrolled port statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <port_stats>: Valid pointer to Ipnet_portif_stats structure to hold retrieved stats
|
|
* \i <cp>: Set to TRUE for Controlled port, or FALSE for uncontrolled port
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (port_stats is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_port_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipnet_portif_stats *port_stats,
|
|
Ip_bool cp
|
|
);
|
|
|
|
#ifdef IPMACSEC_USE_STATS
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_rx_sc_stats - Retrieve the specified SecY Rx SC statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sc_stats>: Valid pointer to Ipnet_secy_sc_stats structure to hold the retrieved stats
|
|
* \i <sci>: Pointer to SCI for Rx SC whose stats are to be retrieved (Cannot be NULL).
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (sc_stats is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_rx_sc_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sc_stats *sc_stats,
|
|
Ip_u8 *sci
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_tx_sc_stats - Retrieve the SecY Tx SC statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sc_stats>: Valid pointer to Ipnet_secy_sc_stats structure to hold the retrieved stats
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (sc_stats is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_tx_sc_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sc_stats *sc_stats
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_rx_sa_stats - Retrieve the specified SecY Rx SA statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_stats>: Valid pointer to Ipnet_secy_sa_stats structure to hold the retrieved stats
|
|
* \i <sci>: Pointer to SCI for Rx SC corresponding to the Rx SA whose stats are to be retrieved (Cannot be NULL).
|
|
* \i <an>: Association number for the RX SA. Must be <= maxRxKeys otherwise a failure will occur.
|
|
* \i <ref>: SA reference. must match the existing SA reference for the SA stats to be successfully retrieved.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (sa_stats is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_rx_sa_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_stats *sa_stats,
|
|
Ip_u8 *sci,
|
|
Ip_u8 an,
|
|
Ip_u32 ref
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_get_tx_sa_stats - Retrieve the specified SecY Tx SA statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sa_stats>: Valid pointer to Ipnet_secy_sa_stats structure to hold retrieved stats
|
|
* \i <an>: Association number for the TX SA. Must be <= maxTxKeys otherwise a failure will occur.
|
|
* \i <ref>: SA reference. must match the existing SA reference for the SA stats to be successfully retrieved.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error (sa_stats is not updated)
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_get_tx_sa_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_sa_stats *sa_stats,
|
|
Ip_u8 an,
|
|
Ip_u32 ref
|
|
);
|
|
#endif
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_stats - Dump (to stdout) the SecY statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_print_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lmi_handle,
|
|
char *ifname
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_port_stats - Dump (to stdout) the SecY Contolled or Uncontrolled port statistics
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <cp>: Set to TRUE for Controlled port, or FALSE for uncontrolled port
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_print_port_stats
|
|
(
|
|
IPMACSEC_LMI_HANDLE lmi_handle,
|
|
char *ifname,
|
|
Ip_bool cp
|
|
);
|
|
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_key_info - Dump (to stdout) the Key information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name used to print the key info.
|
|
* \i <key_id>: Pointer to key identifier of key whose info to print.
|
|
* If NULL, all installed keys will have their info printed.
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \ie
|
|
* RETURNS:
|
|
* 0 upon success, <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_key_info
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ipmacsec_secy_key_id *key_id,
|
|
IP_CONST char *prefix
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_rx_sc - Dump (to stdout) the specified Rx SC status information (and optionally statistics)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: Pointer to SCI for Rx SC whose info is to be printed
|
|
* If NULL, all RX SC info will be printed.
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \i <display_stats>: Indicates whether statistics should be displayed or not.
|
|
* \ie
|
|
* RETURNS:
|
|
* 0 upon success, <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_rx_sc
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname, Ip_u8 *sci,
|
|
IP_CONST char *prefix,
|
|
Ip_bool display_stats
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_tx_sc - Dump (to stdout) the Tx SC status information (and optionally statistics)
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \i <display_stats>: Indicates whether statistics should be displayed or not.
|
|
* \ie
|
|
* RETURNS:
|
|
* 0 upon success, <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_tx_sc
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
IP_CONST char *prefix,
|
|
Ip_bool display_stats
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_rx_sa - Dump (to stdout) the specified Rx SA status information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <sci>: Pointer to SCI for Rx SC corresponding to the RX SA
|
|
* whose info is to be printed (Cannot be NULL).
|
|
* \i <an>: Association number for the RX SA. Must be <= maxRxKeys otherwise a failure will occur.
|
|
* If < 0, then info for all created RX SAs for the specified SC are printed.
|
|
* \i <ref>: SA reference. Ignored if an < 0, otherwise must match
|
|
* the existing SA reference for the SA info to be printed.
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \i <display_stats>: Indicates whether statistics should be displayed or not.
|
|
* \ie
|
|
* RETURNS:
|
|
* 0 upon success, <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_rx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_u8 *sci,
|
|
int an,
|
|
Ip_u32 ref,
|
|
IP_CONST char *prefix,
|
|
Ip_bool display_stats
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_tx_sa - Dump (to stdout) the specified Tx SA status information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <an>: Association number for the TX SA. Must be <= maxTxKeys otherwise a failure will occur.
|
|
* If < 0, then info for all created TX SAs are printed.
|
|
* \i <ref>: SA reference. Ignored if an < 0, otherwise must match
|
|
* the existing SA reference for the SA info to be printed.
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \i <display_stats>: Indicates whether statistics should be displayed or not.
|
|
* \ie
|
|
* RETURNS:
|
|
* 0 upon success, <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_tx_sa
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
int an,
|
|
Ip_u32 ref,
|
|
IP_CONST char *prefix,
|
|
Ip_bool display_stats
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_cipher_suite_info - Dump (to stdout) the supplied Cipher Suite information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <desc>: A pointer to a valid cipher Suite Descriptor to be displayed.
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \i <include_details>: If set, the cipher suite details are displayed,
|
|
* otherwise just the name, index and identifier of the cipher suite are displayed.
|
|
* \ie
|
|
* RETURNS:
|
|
* 0 upon success, <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_cipher_suite_info
|
|
(
|
|
Ipmacsec_ciphersuite_descriptor *desc,
|
|
IP_CONST char *prefix,
|
|
Ip_bool include_details
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_cipher_suite_list - Dump (to stdout) all SecY supported Cipher Suite information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \i <include_details>: If set, the cipher suite details are displayed,
|
|
* otherwise just the name, index and identifier of the cipher suite are displayed.
|
|
* \ie
|
|
* RETURNS:
|
|
* 0 upon success, <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_cipher_suite_list
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
IP_CONST char *prefix,
|
|
Ip_bool include_details
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_print_port_info - Dump (to stdout) the SecY Contolled or Uncontrolled port Control and Status information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <prefix>: An optional prefix string to prepend to output lines.
|
|
* \i <cp>: Set to TRUE for Controlled port, or FALSE for uncontrolled port
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC int ipmacsec_lmi_secy_print_port_info
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
IP_CONST char *prefix,
|
|
Ip_bool cp
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_dump - Dump (to stdout) all the SecY information
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <lh>: an optional lmi handle created using ipmacsec_lmi_handle_create()
|
|
* \i <ifname>: Interface name (NULL terminated string)
|
|
* \i <display_stats>: Indicates whether statistics should be displayed or not.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 on error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_secy_dump
|
|
(
|
|
IPMACSEC_LMI_HANDLE lh,
|
|
char *ifname,
|
|
Ip_bool display_stats
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_monitor_start - Start a MACsec monitor
|
|
* Start a MACsec monitor loop to capture all notifications and either
|
|
* print (to stdout) all their contents, or provide them to the supplied callback routine.
|
|
* Runs in the caller context until the timeout expires or it receives an exit signal,
|
|
* or (if one is supplied) the callback routine indicates an exit (returns a negative value) when invoked.
|
|
* Used mainly by KaY, or for debugging or network management/monitoring.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <timeout>: timeout value in seconds. If >0, then the callback routine is called when a timeout occurs (see below).
|
|
* \i <exit_on_error>: If set, the monitor will exit when an error is encountered when receiving or processing notifications.
|
|
* \i <pid>: (optional) pointer to variable updated (if not NULL) with the pid value of the started monitor
|
|
* (The pid value is to be used when calling ipmacsec_lmi_monitor_exit()).
|
|
* \i <callback>: Optional callback routine provided by the caller to replace the default callback that just
|
|
* prints notification contents (to stdout).
|
|
* The callback MUST have the function prototype IPMACSEC_NL_CB: int (*)(struct Ip_nlmsghdr *nlmsg, int error)
|
|
* If the callback returns a value <0, then the monitor process will exit, otherwise it will continue in the
|
|
* absence of a fatal error or exit signal.
|
|
* The callback will be invoked under these conditions:
|
|
* 1- For every successfully received notification message the callback will be invoked passing a pointer
|
|
* to the nlmsg containing the received netlink notification message, and an error value of 0 is supplied.
|
|
* 2- It will be invoked upon timeouts (if a timeout >0 was specified), in which case a NULL nlmsg pointer is provided
|
|
* and a positive error value is supplied.
|
|
* 3- It will be invoked if errors occur when receiving or processing notifications and if the exit_loop_on_error is not set.
|
|
* In this case, a NULL nlmsg pointer is provided and a negative error value is supplied.
|
|
* 4- It will be invoked when a MACsec monitor EXIT message is received, in which case a
|
|
* pointer to the EXIT nlmsg is provided and a positive error value is supplied.
|
|
* The monitor will only exit upon one of these conditions:
|
|
* 1- An error occurs during its initialization.
|
|
* 2- An error occurs while receiving or processing notifications and the exit_loop_on_error flag is set.
|
|
* 3- The callback routine returns <0 after being invoked.
|
|
* 4- A MACsec monitor EXIT signal is received (i.e. ipmacsec_lmi_monitor_exit() called with the appropriate pid).
|
|
* Note that if the monitor is started with a timeout value of 0, it may block forever if none of the above conditions are met.
|
|
* If a custom callback is used, one can either set the timeout value to a certain reasonable value which
|
|
* causes the callback to be invoked and which in turn can return -1 to cause the monitor to exit.
|
|
* Or if the timeout value is 0, ipmacsec_lmi_monitor_exit() can be used to send a an exit message to cause the monitor to exit.
|
|
* \i <nl_groups>: (Optional) netlink groups for monitor to register for. If set to 0, then
|
|
* (IP_NLMSG_GROUP_MASK(IPMACSEC_NLGRP_NOTIFY) | IP_NLMSG_GROUP_MASK(IPMACSEC_NLGRP_MONITOR))
|
|
* will be used.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon successful exit (timing out is a successful exit),
|
|
* an Ipmacsec_lmi_error <0 upon exit with error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_monitor_start
|
|
(
|
|
Ip_u32 timeout,
|
|
Ip_bool exit_on_error,
|
|
Ip_u32 *pid,
|
|
void *callback,
|
|
Ip_u32 nl_groups
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_monitor_exit - Send an exit signal to the specified monitor
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <pid>: pid of monitor to signal for exit
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 upon error
|
|
*/
|
|
IP_PUBLIC Ipmacsec_lmi_error ipmacsec_lmi_monitor_exit
|
|
(
|
|
Ip_u32 pid
|
|
);
|
|
|
|
/*****************************************************************************
|
|
* ipmacsec_lmi_secy_setup_profile - Setup a SecY using a preconfigured profile
|
|
* Note that the SecY will be disabled before the setup is done to clear any existing settings.
|
|
* However it is up to the caller to enable the SecY after successful setup.
|
|
* As a prerequisite to calling this function, the interface must be attached 1st.
|
|
* PARAMETERS:
|
|
* \is
|
|
* \i <ifname>: Interface name to setup. Must be attached 1st otherwise this test will fail.
|
|
* \i <ut_profile>: Pointer to a valid profile to use.
|
|
* \ie
|
|
* RETURNS:
|
|
* IPMACSEC_LMIERR_NONE upon success,
|
|
* an Ipmacsec_lmi_error <0 upon error
|
|
*/
|
|
IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_secy_setup_profile
|
|
(
|
|
char *ifname,
|
|
Ipmacsec_secy_profile *ut_profile
|
|
);
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif
|
|
|
|
#endif
|
|
|
|
/*
|
|
****************************************************************************
|
|
* END OF FILE
|
|
****************************************************************************
|
|
*/
|