/* ipmacsec_lmi.h - MACsec LMI 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,01Apr10,mry Created */ #ifndef IPMACSEC_LMI_H #define IPMACSEC_LMI_H /* **************************************************************************** * 1 DESCRIPTION **************************************************************************** */ /* This header file is to be included by internal or external modules using * IPMACSEC LMI commands and notifications directly (i.e not using the * LMI public APIs). * Note: It is recommended to use the public LMI API instead of directly * using these commands, for ease of use and consistency reasons, * but sometimes using the commands directly may be more efficient for * certain applications. */ /* **************************************************************************** * 2 CONFIGURATION **************************************************************************** */ /* **************************************************************************** * 3 INCLUDE FILES **************************************************************************** */ #ifdef IP_PORT_VXWORKS #include #endif #include #include #include "ipmacsec.h" #ifdef __cplusplus extern "C" { #endif /* **************************************************************************** * 4 DEFINES **************************************************************************** */ /* Validation Macros */ #define IPMACSEC_LMICMD_IS_VALID(cmd) ((cmd) > __IPMACSEC_LMICMD_NONE) && ((cmd) < __IPMACSEC_LMICMD_MAX) #define IPMACSEC_LMINOTE_IS_VALID(note) ((note) > __IPMACSEC_LMINOTE_NONE) && ((note) < __IPMACSEC_LMINOTE_MAX) #define IPMACSEC_SECY_STATUS_IS_VALID(status) ((status) > __IPMACSEC_STATUS_NONE) && ((status) < __IPMACSEC_STATUS_MAX) #define IPMACSEC_SECY_INFO_IS_VALID(info) ((info) > __IPMACSEC_INFO_NONE) && ((info) < __IPMACSEC_INFO_MAX) /* SI units */ #define IPMACSEC_SECY_COUNTER_1K 1000LLU #define IPMACSEC_SECY_COUNTER_1M (IPMACSEC_SECY_COUNTER_1K*IPMACSEC_SECY_COUNTER_1K) #define IPMACSEC_SECY_COUNTER_1G (IPMACSEC_SECY_COUNTER_1M*IPMACSEC_SECY_COUNTER_1K) #define IPMACSEC_SECY_COUNTER_1T (IPMACSEC_SECY_COUNTER_1G*IPMACSEC_SECY_COUNTER_1K) #define IPMACSEC_SECY_COUNTER_1P (IPMACSEC_SECY_COUNTER_1T*IPMACSEC_SECY_COUNTER_1K) #define IPMACSEC_SECY_COUNTER_1E (IPMACSEC_SECY_COUNTER_1P*IPMACSEC_SECY_COUNTER_1K) /* Used when passing an IPMACSEC_LMI_HANDLE to ipmacsec_lmi_cmd_send() */ #define IPMACSEC_LMI_TO_NETLINK_HANDLE(lh) (Ipmacsec_netlink_handle *)(lh) /* Common definitions */ #define IPMACSEC_LMICMD_ISGET IP_TRUE #define IPMACSEC_LMICMD_ISSET IP_FALSE /* **************************************************************************** * 5 TYPES **************************************************************************** */ struct Ipmacsec_netlink_handle_struct ; /* * Layer Management Interface Commands: (qualified by an explicit set/get indication) * =================================== * Usage: * ----- * Used by both KaY and network management * (May be used by 3rd party applications but use of the public LMI API is recommended instead). * - Set command requests may contain 0 or more parameters, but responses contain no parameters. * - Get command requests may contain 0 or more parameters, and responses must contain 1 or more parameters. * * Note that although some commands allow both Set/Get operations, access to the Set operation * may be only allowed for KaY and disallowed for network management. This is not * enforced at this LMI layer though, but instead should be enforced at the network management layer. * * For reference, we note below which of these Set operations are (or may be) restricted/prohibited * for network management (with reference to the appropriate 802.1AE section and/or PICS PROFORMA section). * */ typedef enum { __IPMACSEC_LMICMD_NONE = 0, /* ---------------------------------------------------------------------------- START ---------------------------------------------------------------------------- */ /* ---------------------------------------------------------------------------- Command to verify if a SecY instance exists (i.e. interface exists and has SecY initialized on it) USAGE: This command has no request or response parameters. A successful response to this command implicitly indicates the existance of the SecY instance. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_EXISTS, /* Only Get allowed */ /* ---------------------------------------------------------------------------- Command to enable/disable SecY instances or check their enabled status USAGE: - Set command requests have a boolean parameter indicating the desired enable status. - Get command requests have no parameters, but their responses contain a boolean parameter indicating the enable status. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_ENABLED, /* Get/Set allowed */ /* ---------------------------------------------------------------------------- Commands to set/get SecY Control fields USAGE: - PROTECT_FRAMES, ALWAYS_INC_SCI, USE_ES, USE_SCB, - REPLAY_PROTECT: Set command requests have an Ip_bool parameter with the value to set, while Get command responses have an Ip_bool parameter with the current value in the SecY. - VALIDATE_FRAMES: Set command requests have an Ipmacsec_validateFrames_type parameter with a valid value to set, while Get command responses have an Ipmacsec_validateFrames_type parameter with the current value in the SecY. - REPLAY_WINDOW: Set command requests have an Ip_u32 parameter with the value to set, while Get command responses have an Ip_u32 parameter with the current value in the SecY. For all the above commands, set is only allowed when SecY is disabled, otherwise set operation will fail. For all the above commands, get command requests contain no parameters. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_PROTECT_FRAMES, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.2) */ IPMACSEC_LMICMD_SECY_ALWAYS_INC_SCI, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.2) */ IPMACSEC_LMICMD_SECY_USE_ES, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.2) */ IPMACSEC_LMICMD_SECY_USE_SCB, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.2) */ IPMACSEC_LMICMD_SECY_VALIDATE_FRAMES, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.2) */ IPMACSEC_LMICMD_SECY_REPLAY_PROTECT, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.2) */ IPMACSEC_LMICMD_SECY_REPLAY_WINDOW, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.2) */ /* ---------------------------------------------------------------------------- Commands to set/get SecY Config fields USAGE: - TX_SCI: Set command request has an SCI parameter and is only allowed when the SecY is disabled. If the SecY is enabled, the result will be a failure without the TX SCI being changed. The Get command request has no parameter, but the response has an SCI parameter. - MAX_RX_SC, MAX_RX_KEYS, MAX_TX_KEYS: The Get command request has no parameters and the response contains an Ip_u16 with the corresponding requested value. - PN_THRESHOLD: Set command request has an Ip_u32 PN threshold parameter. This command can be issued at any time whether the SecY is enabled or disabled. PN threshold value must be > 0 otherwise the set command will fail. Get command request has no parameter, but the response has an Ip_u32 parameter containing the current configured PN threshold. - INFO_NOTIFY: Set requests have a boolean parameter indicating the desired enable/disable state used to enable/disable informational notifications for the specified SecY. Get requests have no parameter, but responses have a boolean parameter indicating the current enable/disable state for informational notifications. - CONFIDENTIALITY_OFFSET: Set/Get the SecY confidentialityOffset to be used by ciphers supporting offsetConfidentiality (ciphers not supporting offsetConfidentiality will fail to intialize if this value is set, although the set operation does not fails). The Set command request has a valid Ip_u16 parameter containing the confidentialityOffset value It is only allowed when the SecY is disabled. If the SecY is enabled, the result will be a failure without the SecY confidentialityOffset being changed. The Get command request has no parameters, the response contains an Ip_u16 parameter with the currently configured SecY confidentialityOffset value. - CURRENT_CIPHER_SUITE: Set/Get the SecY current cipher suite. The Set command request has a valid supported Ipmacsec_cipher_suite_index parameter. It is only allowed when the SecY is disabled. If the SecY is enabled, the result will be a failure without the SecY cipher suite being changed. The Get command request has no parameters, the response contains an Ipmacsec_ciphersuite_descriptor parameter corresponding to the SecY's current cipher suite. - CIPHER_SUITE_LIST: retrieves a list of all supported Cipher Suites. The Get command request has no parameters, the response contains a list of Ipmacsec_ciphersuite_descriptor structures as parameters. - CIPHER_SUITE_INFO: retrieves cipher suite info for the specified cipher suite. The Get command request has an Ipmacsec_cipher_suite_index parameter, the response contains a Ipmacsec_ciphersuite_descriptor parameter if the cipher suite is valid and supported, otherwise the command fails. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_TX_SCI, /* Get/Set allowed (Set is prohibited for network management) (A.11.1) */ IPMACSEC_LMICMD_SECY_MAX_RX_SC, /* Only Get allowed (A.11.1) */ IPMACSEC_LMICMD_SECY_MAX_RX_KEYS, /* Only Get allowed (A.11.1) */ IPMACSEC_LMICMD_SECY_MAX_TX_KEYS, /* Only Get allowed (A.11.1) */ IPMACSEC_LMICMD_SECY_PN_THRESHOLD, /* Set/Get allowed (A.11-KAY-9, 8.2.7) */ IPMACSEC_LMICMD_SECY_INFO_NOTIFY, /* Set/Get allowed */ IPMACSEC_LMICMD_SECY_CONFIDENTIALITY_OFFSET,/* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.3, 10.7.25) */ IPMACSEC_LMICMD_SECY_CURRENT_CIPHER_SUITE, /* Get/Set allowed (Set may be restricted for network management) (A.11.1, A.11.3, 10.7.25) */ IPMACSEC_LMICMD_SECY_CIPHER_SUITE_LIST, /* Only Get allowed (A.11.1, 10.7.24) */ IPMACSEC_LMICMD_SECY_CIPHER_SUITE_INFO, /* Only Get allowed (A.11.1, 10.7.24) */ /* ---------------------------------------------------------------------------- Commands to get SecY Operational fields USAGE: The Get command requests have no parameters, and the responses contain an Ip_u16 with the corresponding requested value. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_NUM_RX_SC_ACTIVE, /* Only Get allowed */ IPMACSEC_LMICMD_SECY_NUM_RX_SC_CREATED, /* Only Get allowed */ /* ---------------------------------------------------------------------------- SAK related commands USAGE: - KEY_INSTALL command requests are followed by an Ipmacsec_secy_key_descriptor parameter with the appropriate key_id, key_size and key_type fields set. This is followed by a parameter containing the keying material. - KEY_REMOVE command requests are followed by an Ipmacsec_secy_key_descriptor parameter with the proper key_id field set. - KEY_PURGE command requests have no parameters and will only purge keys not currently in use. - KEY_INFO command requests are followed by an Ipmacsec_secy_key_descriptor parameter with the proper key_id field set. While command responses contain a single Ipmacsec_secy_key_descriptor parameter. - KEY_LIST command requests have no parameters, and responses contain 0 or more Ipmacsec_secy_key_descriptor parameter(s). Note that no actual Keying matrial is retrieved with KEY_INFO or KEY_LIST commands. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_KEY_INSTALL, /* Only Set allowed (May be restricted for network management) (A.11.3, 10.7.25) */ IPMACSEC_LMICMD_SECY_KEY_REMOVE, /* Only Set allowed (May be restricted for network management) (A.11.3, 10.7.25) */ IPMACSEC_LMICMD_SECY_KEY_PURGE, /* Only Set allowed (May be restricted for network management) (A.11.3, 10.7.25) */ IPMACSEC_LMICMD_SECY_KEY_INFO, /* Only Get allowed (A.11.1, 10.7.27) */ IPMACSEC_LMICMD_SECY_KEY_LIST, /* Only Get allowed */ /* ---------------------------------------------------------------------------- Commands to manipulate SecY SCs USAGE: All RX_SC_* command requests (except RX_SC_LIST) are followed by an sci parameter. - RX_SC_STATUS responses contain a single Ipmacsec_secy_sc_info parameter. - RX_SC_LIST responses contain 0 or more Ipmacsec_secy_sc_info parameters All TX_SC_* command requests contain no parameters. - TX_SC_CREATE will use the SCI previously configured using SECY_TX_SCI or the default SCI if applicable. If there is no valid SCI value configured, this command will fail. - TX_SC_STATUS responses contain a single Ipmacsec_secy_sc_info parameter ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_RX_SC_CREATE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.11) */ IPMACSEC_LMICMD_SECY_RX_SC_DELETE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.11) */ IPMACSEC_LMICMD_SECY_RX_SC_STATUS, /* Only Get allowed (10.7.12) */ IPMACSEC_LMICMD_SECY_RX_SC_LIST, /* Only Get allowed (10.7.12) */ IPMACSEC_LMICMD_SECY_TX_SC_CREATE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.11) */ IPMACSEC_LMICMD_SECY_TX_SC_DELETE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.11) */ IPMACSEC_LMICMD_SECY_TX_SC_STATUS, /* Only Get allowed (10.7.20) */ /* ---------------------------------------------------------------------------- Commands to manipulate SecY SAs USAGE: - *_SA_CREATE command requests are followed by an Ipmacsec_secy_sa_descriptor parameter with the "sci" (only for RX), "an", "ref" and "key_id" fields properly set, additionally an Ipmacsec_secy_sa_info parameter is added with the appropriate "config" fields set. - *_SA_CONTROL command requests are followed by an Ipmacsec_secy_sa_descriptor parameter with the "sci" (only for RX), "an", and "ref" fields properly set, additionally an Ipmacsec_secy_sa_ctrl parameter is added with the appropriate fields set. - *_SA_DELETE/SA_STATUS command requests are followed by an Ipmacsec_secy_sa_descriptor parameter with the "sci" (only for RX), "an", and "ref" fields properly set. - *_SA_STATUS responses contain exactly one {Ipmacsec_secy_sa_descriptor+Ipmacsec_secy_sa_info +Ipmacsec_secy_sa_ctrl} parameter tuple (if successful), - RX_SA_LIST command requests have the corresponding RX SC sci as a parameter - TX_SA_LIST command requests have no parameters. both *_SA_LIST responses contain 0 or more {Ipmacsec_secy_sa_descriptor+Ipmacsec_secy_sa_info +Ipmacsec_secy_sa_ctrl} parameter tuples. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_RX_SA_CREATE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.13) */ IPMACSEC_LMICMD_SECY_RX_SA_DELETE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.13) */ IPMACSEC_LMICMD_SECY_RX_SA_CONTROL, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.15) */ IPMACSEC_LMICMD_SECY_RX_SA_STATUS, /* Only Get allowed (10.7.14) */ IPMACSEC_LMICMD_SECY_RX_SA_LIST, /* Only Get allowed (10.7.14) */ IPMACSEC_LMICMD_SECY_TX_SA_CREATE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.21) */ IPMACSEC_LMICMD_SECY_TX_SA_DELETE, /* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.21) */ IPMACSEC_LMICMD_SECY_TX_SA_CONTROL,/* Only Set allowed (May be restricted for network management) (A.11, A.11.3, 10.7.23) */ IPMACSEC_LMICMD_SECY_TX_SA_STATUS, /* Only Get allowed (10.7.22) */ IPMACSEC_LMICMD_SECY_TX_SA_LIST, /* Only Get allowed (10.7.14) */ /* ---------------------------------------------------------------------------- Commands to get SecY/SC/SA Statistics USAGE: Get Commands: - SECY_STATS command requests have no parameters, while responses have an Ipmacsec_secy_stats parameter - RX_SC_STATS command requests have an sci parameter, while responses have an Ipmacsec_secy_sc_stats parameter - TX_SC_STATS command requests have no parameters, while responses have an Ipmacsec_secy_sc_stats parameter - *_SA_STATS command requests have an Ipmacsec_secy_sa_descriptor parameter, ("an" and "ref" fields are mandatory for all and the "sci" field is mandatory only for RX SAs. Other fields are ignored). responses have an Ipmacsec_secy_sa_stats parameter. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_STATS, /* Only Get allowed (A.11.4) - Covers SecY Verification/Validation and Protection/Generation Stats */ IPMACSEC_LMICMD_SECY_RX_SC_STATS, /* Only Get allowed (A.11.4) */ IPMACSEC_LMICMD_SECY_TX_SC_STATS, /* Only Get allowed (A.11.4) */ IPMACSEC_LMICMD_SECY_RX_SA_STATS, /* Only Get allowed (A.11.4) */ IPMACSEC_LMICMD_SECY_TX_SA_STATS, /* Only Get allowed (A.11.4) */ /* ---------------------------------------------------------------------------- Commands to manipulate both controlled and uncontrolled ports (except where noted) USAGE: - CONTROLLED_PORT_ENABLED: Get/Set ControlledPortEnabled control of the Controlled Port (10.7.5) Get command requests have no parameters, and their responses contain a boolean parameter indicating the current ControlledPortEnabled state. Set command requests have a boolean parameter indicating the desired ControlledPortEnabled state to set. - PORT_MAC_ENABLED, PORT_MAC_OPER, PORT_OPER_PTP_MAC: Get the MAC_Enabled, MAC_Operational or operPointToPointMAC status of the SecY Controlled or Uncontrolled port (10.7.2, 10.7.4) - PORT_ADMIN_PTP_MAC: Get/Set adminPointToPointMAC control of the Controlled Port ONLY (6.5, 6.7) Get command requests have no parameters, and their responses contain a Ip_portif_admin_ptp_mac_val parameter indicating the current adminPointToPointMAC. Set command requests have a Ip_portif_admin_ptp_mac_val parameter indicating the desired adminPointToPointMAC state to set. - PORT_STATISTICS: Get command requests have a boolean parameters set if Controlled Port statistics are requested, otherwise cleared for Uncontrolled Port stats. Responses have an Ipnet_portif_stats parameter ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_CONTROLLED_PORT_ENABLED, /* Get/Set allowed (A.11-KAY-2) (Set is prohibited for network management) */ IPMACSEC_LMICMD_PORT_MAC_ENABLED, /* Only Get allowed (A.11.1) */ IPMACSEC_LMICMD_PORT_MAC_OPER, /* Only Get allowed (A.11.1) */ IPMACSEC_LMICMD_PORT_OPER_PTP_MAC, /* Only Get allowed (A.11.1) */ IPMACSEC_LMICMD_PORT_ADMIN_PTP_MAC, /* Get/Set allowed (for Controlled port Only) (6.5, 6.7) */ IPMACSEC_LMICMD_PORT_STATISTICS, /* Get/Set allowed (A.11.4) */ /* ---------------------------------------------------------------------------- Commands to reset SecY/CP Statistics USAGE: - RESET_STATISTICS: Set command request has no parameters. It causes the SecY statistics (including corresponding Controlled Port stats) to be cleared (reset to 0). This command 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 cleared upon disabling the SecY since all SCs/SAs are deleted when a SecY is disabled. ---------------------------------------------------------------------------- */ IPMACSEC_LMICMD_SECY_RESET_STATISTICS, /* Only Set allowed (A.11.4) */ /* ---------------------------------------------------------------------------- END ---------------------------------------------------------------------------- */ __IPMACSEC_LMICMD_MAX /* DO NOT MODIFY THIS. MUST BE LAST */ } Ipmacsec_lmi_command; /* Layer Management Interface Notifications: * ======================================== * These are notifications types recieved by the registered SecY monitor callback. * */ typedef enum { __IPMACSEC_LMINOTE_NONE = 0, /* ---------------------------------------------------------------------------- START ---------------------------------------------------------------------------- */ /* ---------------------------------------------------------------------------- Status Notification events USAGE: Status Notification messages contain an Ipmacsec_nlnote_hdr with note set to this value, followed by an Ipmacsec_secy_status parameter, and possibly additional paramter(s) depending on status value (see status notification descriptions below). ---------------------------------------------------------------------------- */ IPMACSEC_LMINOTE_STATUS, /* ---------------------------------------------------------------------------- Informational Notification events; Mainly used by monitors for debugging SecY USAGE: Informational Notification messages contain an Ipmacsec_nlnote_hdr with note set this value, followed by an Ipmacsec_secy_info parameter, and possibly additional paramter(s) depending on info value (see info notification descriptions below). ---------------------------------------------------------------------------- */ IPMACSEC_LMINOTE_INFO, /* ---------------------------------------------------------------------------- END ---------------------------------------------------------------------------- */ __IPMACSEC_LMINOTE_MAX /* DO NOT MODIFY THIS. MUST BE LAST */ } Ipmacsec_lmi_note; /* MACsec status notifications: * =========================== */ typedef enum { __IPMACSEC_STATUS_NONE = 0, /* ---------------------------------------------------------------------------- START ---------------------------------------------------------------------------- */ /* ---------------------------------------------------------------------------- Status Notification for ControlledPortEnabled becoming TRUE/FALSE USAGE: This status notification messages does not contain any additional parameters. ---------------------------------------------------------------------------- */ IPMACSEC_STATUS_SECY_CP_ENABLED_ON, IPMACSEC_STATUS_SECY_CP_ENABLED_OFF, /* ---------------------------------------------------------------------------- Status Notification for Controlled Port MAC_Enabled becoming TRUE/FALSE USAGE: This status notification messages does not contain any additional parameters. ---------------------------------------------------------------------------- */ IPMACSEC_STATUS_SECY_CP_MAC_ENABLED_ON, IPMACSEC_STATUS_SECY_CP_MAC_ENABLED_OFF, /* ---------------------------------------------------------------------------- Status Notification for Controlled Port MAC_Operational becoming TRUE/FALSE USAGE: This status notification messages does not contain any additional parameters. ---------------------------------------------------------------------------- */ IPMACSEC_STATUS_SECY_CP_MAC_OPER_ON, IPMACSEC_STATUS_SECY_CP_MAC_OPER_OFF, /* ---------------------------------------------------------------------------- Status Notification for Controlled Port operPointToPointMAC becoming TRUE/FALSE USAGE: This status notification messages does not contain any additional parameters. ---------------------------------------------------------------------------- */ IPMACSEC_STATUS_SECY_CP_OPER_PTP_MAC_ON, IPMACSEC_STATUS_SECY_CP_OPER_PTP_MAC_OFF, /* ---------------------------------------------------------------------------- Status Notification for TX SA PN nearing exhaustion (8.2.7) USAGE: This status notification messages contains an Ipmacsec_secy_sa_descriptor followed by an Ipmacsec_secy_sa_info as additional parameter corresponding to the TX SA whose PN is nearing exhaustion. ---------------------------------------------------------------------------- */ IPMACSEC_STATUS_SECY_PN_NEARLY_EXHAUSTED, /* ---------------------------------------------------------------------------- Status Notification for TX SA PN being exhausted USAGE: This status notification messages contains an Ipmacsec_secy_sa_descriptor as an additional parameter corresponding to the TX SA whose PN is exhausted. Note that after this notification, the SecY Controlled Port MAC_Operational status will transition to FALSE and transmit/receive will be disabled on the SecY until a new valid TX SA is enabled and ControlledPortEnabled is toggled to FALSE then to TRUE. ---------------------------------------------------------------------------- */ IPMACSEC_STATUS_SECY_PN_EXHAUSTED, /* ---------------------------------------------------------------------------- END ---------------------------------------------------------------------------- */ __IPMACSEC_STATUS_MAX /* DO NOT MODIFY THIS. MUST BE LAST */ } Ipmacsec_secy_status; /* MACsec informational notifications: * ================================== */ typedef enum { __IPMACSEC_INFO_NONE = 0, /* ---------------------------------------------------------------------------- START ---------------------------------------------------------------------------- */ /* ---------------------------------------------------------------------------- Informational Notification for SecY getting enabled USAGE: This info notification messages does not contain any additional parameters. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_ENABLED, /* ---------------------------------------------------------------------------- Informational Notification for SecY getting disabled USAGE: This info notification messages does not contain any additional parameters. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_DISABLED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SC being created USAGE: This info notification messages contains an Ipmacsec_secy_sc_info parameter corresponding to the created SC. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_SC_CREATED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SC being deleted USAGE: This info notification messages contains an sci parameter corresponding to the deleted SC. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_SC_DELETED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SC runtime status changes USAGE: This info notification messages contains an Ipmacsec_secy_sc_info parameter corresponding to the SC whose status changed. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_SC_STATUS_CHANGED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SA being created USAGE: This info notification messages contains an Ipmacsec_secy_sa_descriptor parameter followed by an Ipmacsec_secy_sa_info parameter corresponding to the created SA. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_SA_CREATED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SA being deleted USAGE: This info notification messages contains an Ipmacsec_secy_sa_descriptor parameter corresponding to the deleted SA. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_SA_DELETED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SA runtime status or config changes USAGE: This info notification messages contains an Ipmacsec_secy_sa_descriptor parameter followed by an Ipmacsec_secy_sa_info parameter and an Ipmacsec_secy_sa_ctrl parameter corresponding to the SA whose status changed. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_SA_STATUS_CHANGED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SAK being installed USAGE: This info notification messages contains an Ipmacsec_secy_key_descriptor parameter corresponding to the installed SAK. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_KEY_INSTALLED, /* ---------------------------------------------------------------------------- Informational Notification for SecY SAK being removed USAGE: This info notification messages contains an Ipmacsec_secy_key_descriptor parameter corresponding to the removed SAK. ---------------------------------------------------------------------------- */ IPMACSEC_INFO_SECY_KEY_REMOVED, /* ---------------------------------------------------------------------------- END ---------------------------------------------------------------------------- */ __IPMACSEC_INFO_MAX /* DO NOT MODIFY THIS. MUST BE LAST */ } Ipmacsec_secy_info; /* **************************************************************************** * 6 FUNCTIONS **************************************************************************** */ /* **************************************************************************** * 7 Netlink Command/Send API **************************************************************************** */ /* *=========================================================================== * ipmacsec_lmi_secy_set_cmd_append *=========================================================================== * Description: Append a SecY Set command (with optional parameter) * to exisiting buffer. * Parameters: buf - Properly allocated buffer container. * nlreq - An optional pointer that will be updated with a pointer * to the created netlink message upon successful return. * ifname - Interface name (NULL terminated string) for the SecY to * send cmd to. * cmd - LMI Command to send * param - (optional) pointer to command parameter * (IP_NULL ==> no param specified) * param_size - (optional) parameter size (0 ==> no param specified) * Returns: IPMACSEC_LMIERR_NONE upon success. * Ipmacsec_lmi_error <0 upon error. * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_secy_set_cmd_append(Ipmacsec_buffer *buf, struct Ip_nlmsghdr **nlreq, char *ifname, Ipmacsec_lmi_command cmd, void *param, Ip_u32 param_size); /* *=========================================================================== * ipmacsec_lmi_secy_get_cmd_append *=========================================================================== * Description: Append a SecY Get command (with optional parameter) * to exisiting buffer. * Parameters: buf - Properly allocated buffer container. * nlreq - An optional pointer that will be updated with a pointer * to the created netlink message upon successful return. * ifname - Interface name (NULL terminated string) for the SecY to * send cmd to. * cmd - LMI Command to send * param - (optional) pointer to command parameter * (IP_NULL ==> no param specified) * param_size - (optional) parameter size (0 ==> no param specified) * Returns: IPMACSEC_LMIERR_NONE upon success. * Ipmacsec_lmi_error <0 upon error. * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_secy_get_cmd_append(Ipmacsec_buffer *buf, struct Ip_nlmsghdr **nlreq, char *ifname, Ipmacsec_lmi_command cmd, void *param, Ip_u32 param_size); /* *=========================================================================== * ipmacsec_lmi_cmd_parse_response *=========================================================================== * Description: Parse a SecY Get command response and retrieve any applicable * parameter. * NOTE that if multiple responses with the same command are * contained in the buffer, only the 1st one is parsed, so * avoid sending mutli-command requests with duplicate get commands. * Also if param & param_size are not 0 (i.e. a parameter is expected) * and none are found, an error is returned. If no returned * parameter is an acceptable result, use ipmacsec_lmi_cmd_parse_response_pbuf() * instead. * * Parameters: buf - buffer container containing the netlink message to parse * for the cmd response. * ifname - Interface name (NULL terminated string) associated with * the SecY cmd. * cmd - LMI Command to parse * param - (optional) pointer to buffer to hold the response parameter * (IP_NULL ==> no param retrieved) * param_size - (optional) parameter buffer size (0 ==> no param retrieved) * Returns: IPMACSEC_LMIERR_NONE upon success. * Ipmacsec_lmi_error <0 upon error. * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_cmd_parse_response(Ipmacsec_buffer *buf, char *ifname, Ipmacsec_lmi_command cmd, void *param, Ip_u32 param_size); /* *=========================================================================== * ipmacsec_lmi_cmd_parse_response_pbuf *=========================================================================== * Description: Parse a SecY Get command response and retrieve any available * parameter(s) into supplied container. * NOTE that if multiple response with the same command are * contained in the buffer, only the 1st one is parsed, so * avoid sending mutli-command requests with duplicate get commands. * Also if the supplied buffer does not have enough space for all * the retrieved parameter, retrieval will still succeed, but the * pbuf will be truncated. * This function will succeed even if no parameters exist as long * as the response is valid. * Parameters: buf - buffer container containing the netlink message to parse * for the cmd response. * ifname - Interface name (NULL terminated string) associated with * the SecY cmd. * cmd - LMI Command to parse * pbuf - A valid buffer container to store the parameter(s). * Returns: IPMACSEC_LMIERR_NONE upon success. * Ipmacsec_lmi_error <0 upon error. * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_cmd_parse_response_pbuf(Ipmacsec_buffer *buf, char *ifname, Ipmacsec_lmi_command cmd, Ipmacsec_buffer *pbuf); /* *=========================================================================== * ipmacsec_lmi_cmd_send *=========================================================================== * Description: Send a command (or optionally multiple commands) contained in the * buffer over a MACsec netlink socket and receive a response if expected * Commnds will get sent/executed in the order they are added. * NOTE: Avoid sending mutli-command requests with duplicate get commands. * Parameters: nlhandle - (Optional) a valid nhandle created by the caller. * If NULL, a temporary nhandle is created then deleted. * request - Valid buffer containing the netlink messages/LMI command(s) * response - (optional) valid allocated buffer container to hold the response * (if any). May be set to NULL if no response is expected * or if caller does not care about response contents. * Returns: IPMACSEC_LMIERR_NONE upon successful execution and positive Acknowledgement of * the LMI command. * Ipmacsec_lmi_error <0 upon failure, error, or negative Acknowledgement * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_cmd_send(struct Ipmacsec_netlink_handle_struct *nlh, Ipmacsec_buffer *request, Ipmacsec_buffer *response); /* *=========================================================================== * ipmacsec_lmi_cmd_send_bool *=========================================================================== * Description: Send a Set/Get command that sets/retrieves a boolean parameter. * Set command requests will contain a boolean parameter set to the value * pointed to by param, while get command requests have no parameter. * Parameters: lh - an optional lmi handle created using ipmacsec_lmi_handle_create() * ifname - Intereface name (NULL terminated string) * cmd - A valid command to send (must be one that sets or gets a boolean param) * param - Pointer to the boolean value to set or retrieve * isGet - Indicates whether the command is a get command (IPMACSEC_LMICMD_ISGET or IP_TRUE) * or set command (IPMACSEC_LMICMD_ISSET or IP_FALSE) * Returns: IPMACSEC_LMIERR_NONE upon success, Ipmacsec_lmi_error <0 upon failure. * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_cmd_send_bool(IPMACSEC_LMI_HANDLE lh, char *ifname, Ipmacsec_lmi_command cmd, Ip_bool *param, Ip_bool isGet); /* *=========================================================================== * ipmacsec_lmi_cmd_send_u16 *=========================================================================== * Description: Send a Set/Get command that sets/retrieves a boolean parameter. * Set command requests will contain an Ip_u16 parameter set to the value * pointed to by param, while get command requests have no parameter. * Parameters: lh - an optional lmi handle created using ipmacsec_lmi_handle_create() * ifname - Intereface name (NULL terminated string) * cmd - A valid command to send (must be one that sets or gets a Ip_u16 param) * param - Pointer to the Ip_u16 value to set or retrieve * isGet - Indicates whether the command is a get command (IPMACSEC_LMICMD_ISGET or IP_TRUE) * or set command (IPMACSEC_LMICMD_ISSET or IP_FALSE) * Returns: IPMACSEC_LMIERR_NONE upon success, Ipmacsec_lmi_error <0 upon failure. * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_cmd_send_u16(IPMACSEC_LMI_HANDLE lh, char *ifname, Ipmacsec_lmi_command cmd, Ip_u16 *param, Ip_bool isGet); /* *=========================================================================== * ipmacsec_lmi_cmd_send_u32 *=========================================================================== * Description: Send a Set/Get command that sets/retrieves a boolean parameter. * Set command requests will contain an Ip_u32 parameter set to the value * pointed to by param, while get command requests have no parameter. * Parameters: lh - an optional lmi handle created using ipmacsec_lmi_handle_create() * ifname - Intereface name (NULL terminated string) * cmd - A valid command to send (must be one that sets or gets an Ip_u32 param) * param - Pointer to the Ip_u32 value to set or retrieve * isGet - Indicates whether the command is a get command (IPMACSEC_LMICMD_ISGET or IP_TRUE) * or set command (IPMACSEC_LMICMD_ISSET or IP_FALSE) * Returns: IPMACSEC_LMIERR_NONE upon success, Ipmacsec_lmi_error <0 upon failure. * */ IP_GLOBAL Ipmacsec_lmi_error ipmacsec_lmi_cmd_send_u32(IPMACSEC_LMI_HANDLE lh, char *ifname, Ipmacsec_lmi_command cmd, Ip_u32 *param, Ip_bool isGet); /* **************************************************************************** * 7 Misc API **************************************************************************** */ /* *=========================================================================== * ipmacsec_parse_sci_string *=========================================================================== * Description: Prase an SCI string to produce an sci value. * Valid SCI formats: * XX-YY-ZZ-WW-UU-VV-PP-QQ * XX:YY:ZZ:WW:UU:VV:PP:QQ * XX YY ZZ WW UU VV PP QQ * XXYYZZWWUUVVPPQQ * where X, Y, Z, W, U, V, P and Q are characters representing value hex digits. * Parameters: sci_string - SCI string to parse * sci - Pointer to buffer in which to store the sci value. * Returns: 0 upon success, <0 otherwise * */ IP_GLOBAL int ipmacsec_parse_sci_string(IP_CONST char *sci_string, Ip_u8 *sci); /* *=========================================================================== * ipmacsec_secy_counter_format *=========================================================================== * Description: Format a counter value in using SI prefixes (K,M,G,T,P,E) as appropriate * Parameters: buf - valid pointer to buffer to format result in. * len - len of buffer (must be large enough to fit result or it will be truncated) * count - counter value to be formatted * Returns: Pointer to formatted string i.e. == "buf" * */ IP_GLOBAL IP_CONST char * ipmacsec_secy_counter_format(char *buf, int len, Ipmacsec_secy_counter64 count); /* *=========================================================================== * ipmacsec_lmi_error_name *=========================================================================== * Description: Return a string describing the name of an LMI error * Parameters: error - error to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_lmi_error_name(Ipmacsec_lmi_error error); /* *=========================================================================== * ipmacsec_lmi_cmd_name *=========================================================================== * Description: Return a string describing the name of an LMI command * Parameters: cmd - Command to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_lmi_cmd_name(Ipmacsec_lmi_command cmd); /* *=========================================================================== * ipmacsec_lmi_note_name *=========================================================================== * Description: Return a string describing the name of an LMI Notification * Parameters: notification - Notification to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_lmi_note_name(Ipmacsec_lmi_note notification); /* *=========================================================================== * ipmacsec_secy_status_name *=========================================================================== * Description: Return a string describing the name of an IPMACsec Status * Parameters: status - Status to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_secy_status_name(Ipmacsec_secy_status status); /* *=========================================================================== * ipmacsec_secy_info_name *=========================================================================== * Description: Return a string describing the name of an IPMACsec Info * Parameters: info - Info to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_secy_info_name(Ipmacsec_secy_info info); /* *=========================================================================== * ipmacsec_lmi_enable_flag_name *=========================================================================== * Description: Return a string describing the enable_flag value * Parameters: enable_flag - value to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_lmi_enable_flag_name(Ipmacsec_enable_flag enable_flag); /* *=========================================================================== * ipmacsec_lmi_confidentiality_name *=========================================================================== * Description: Return a string describing the confidentiality value * Parameters: confidentiality - value to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_lmi_confidentiality_name(Ipmacsec_confidentiality confidentiality); /* *=========================================================================== * ipmacsec_secy_validateFrames_name *=========================================================================== * Description: Return a string describing the validateFrames value * Parameters: validateFrames - validateFrames to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_secy_validateFrames_name(Ipmacsec_validateFrames_type validateFrames); /* *=========================================================================== * ipmacsec_secy_cp_adminPointToPointMAC_name *=========================================================================== * Description: Return a string describing the validateFrames value * Parameters: admin_p2p_mac - admin_p2p_mac to describe * Returns: String pointer (always != NULL) * */ IP_GLOBAL IP_CONST char * ipmacsec_secy_cp_adminPointToPointMAC_name(Ip_portif_admin_ptp_mac_val admin_p2p_mac); /* *=========================================================================== * ipmacsec_lmi_strf_sc_info *=========================================================================== * Description: Format an SC Info struct into a string. * Formatted string will always be NULL terminated. * Parameters: sc_info - Pointer to info to format * prefix - An optional prefix to use in the formatted string * str - Buffer to populate with formatted string. * strln - length of supplied buffer. * Returns: None. * */ IP_GLOBAL void ipmacsec_lmi_strf_sc_info(Ipmacsec_secy_sc_info *sc_info, IP_CONST char *prefix, char *str, Ip_u32 strln); /* *=========================================================================== * ipmacsec_lmi_strf_sa_desc *=========================================================================== * Description: Format an SA Descriptor struct into a string. * Formatted string will always be NULL terminated. * Parameters: sa_desc - Pointer to descriptor to format * prefix - An optional prefix to use in the formatted string * str - Buffer to populate with formatted string. * strln - length of supplied buffer. * Returns: None. * */ IP_GLOBAL void ipmacsec_lmi_strf_sa_desc(Ipmacsec_secy_sa_descriptor *sa_desc, IP_CONST char *prefix, char *str, Ip_u32 strln); /* *=========================================================================== * ipmacsec_lmi_strf_sa_info *=========================================================================== * Description: Format an SA Info struct into a string * Formatted string will always be NULL terminated. * Parameters: sa_info - Pointer to info to format * sa_dir - Direction of the SA corresponding to this info. * prefix - An optional prefix to use in the formatted string * str - Buffer to populate with formatted string. * strln - length of supplied buffer. * Returns: None. * */ IP_GLOBAL void ipmacsec_lmi_strf_sa_info(Ipmacsec_secy_sa_info *sa_info, Ipmacsec_dir sa_dir, IP_CONST char *prefix, char *str, Ip_u32 strln); /* *=========================================================================== * ipmacsec_lmi_strf_sa_ctrl *=========================================================================== * Description: Format an SA Control struct into a string * Formatted string will always be NULL terminated. * Parameters: sa_ctrl - Pointer to ctrl to format * sa_dir - Direction of the SA corresponding to this info. * prefix - An optional prefix to use in the formatted string * str - Buffer to populate with formatted string. * strln - length of supplied buffer. * Returns: None. * */ IP_GLOBAL void ipmacsec_lmi_strf_sa_ctrl(Ipmacsec_secy_sa_ctrl *sa_ctrl, Ipmacsec_dir sa_dir, IP_CONST char *prefix, char *str, Ip_u32 strln); /* *=========================================================================== * ipmacsec_lmi_strf_key_desc *=========================================================================== * Description: Format a Key Descriptor struct into a string. * Formatted string will always be NULL terminated. * Parameters: key_desc - Pointer to descriptor to format * prefix - An optional prefix to use in the formatted string * str - Buffer to populate with formatted string. * strln - length of supplied buffer. * Returns: None. * */ IP_GLOBAL void ipmacsec_lmi_strf_key_desc(Ipmacsec_secy_key_descriptor *key_desc, IP_CONST char *prefix, char *str, Ip_u32 strln); #ifdef __cplusplus } #endif #endif /* **************************************************************************** * END OF FILE **************************************************************************** */