Net.idl

/* SPDX-License-Identifier: BSD-3-Clause */
/*
 * Copyright 2016 Raritan Inc. All rights reserved.
 */
 
#include <Event.idl>
 
/**
 * Network Configuration
 */
module net {
 
    /** IPv4/IPv6 address and prefix len */
    structure IpAddrCidr {
        string                  addr;                   // IP address
        int                     prefixLen;              // Length of network prefix in the IP address
    };
 
    /** IPv4/IPv6 route */
    structure IpRoute {
        IpAddrCidr              destNetAddrCidr;        // Destination network address (CIDR)
        string                  nextHopAddr;            // Address of the next hop (empty when ifName is set)
        string                  ifName;                 // Destination interface (empty if nextHopAddr is set)
    };
 
    /** Role of the node when port forwarding is enabled */
    enumeration PortForwardingRole {
        PRIMARY_UNIT,                                   ///< Node is a port forwarding primary unit
        EXPANSION_UNIT                                  ///< Node is a port forwarding expansion unit
    };
 
    /** Port forwarding settings */
    structure PortForwardingSettings {
        boolean                  enabled;                     ///< Controls if port forwarding is enabled
        PortForwardingRole role;                        ///< The role of the node (primary unit or expansion unit)
        string                   primaryUnitDownstreamIfName; ///< Primary unit downstream interface (usb: any USB iface)
    };
 
    /** DNS settings */
    structure DnsSettings {
        vector<string>          serverAddrs;            ///< List of domain name servers addresses (IPv4/IPv6)
        vector<string>          searchSuffixes;         ///< List of domain search suffixes
        boolean                 resolverPrefersIPv6;    ///< Resolver should prefer IPv6 addresses
    };
 
    /** IP protocol specific routing settings */
    structure IpRoutingSettings {
        vector<IpRoute>         staticRoutes;           ///< List of static routes
    };
 
    /** Routing settings */
    structure RoutingSettings {
        IpRoutingSettings ipv4;                   ///< IPv4 routing settings
        IpRoutingSettings ipv6;                   ///< IPv6 routing settings
    };
 
    /** Common settings */
    structure CommonSettings {
        DnsSettings               dns;            ///< DNS settings
        RoutingSettings           routing;        ///< Routing settings
        PortForwardingSettings    portForwarding; ///< Port forwarding settings
    };
 
    /** Port forwarding primary unit address info for an interface */
    structure PortForwardingPrimaryUnitAddrInfo {
        string                  ifName;                 ///< interface name on primary unit
        string                  addr;                   ///< IPv4/IPv6 address on the interface
    };
 
    /** Port forwarding info */
    structure PortForwardingInfo {
        boolean                 enabled;                ///< \c true if port forwarding is enabled
        boolean                 nodeIndexValid;         ///< \c true if nodeIndex is valid
        int                     nodeIndex;              ///< Index of the node in the port forwarding cascade
        boolean                 expansionUnitConnected; ///< \c true if this node has an expansion unit connected
        string                  primaryUnitDownstreamIfName; ///< Primary unit downstream interface (usb: any USB iface)
        ///< the first entry of each vector has the default route set (if default route is set at all)
        vector<PortForwardingPrimaryUnitAddrInfo> primaryUnitIPv4AddrInfos; ///< Primary unit address info for IPv4
        vector<PortForwardingPrimaryUnitAddrInfo> primaryUnitIPv6AddrInfos; ///< Primary unit address info for IPv6
        string                  linkLocalIPv6Address;   ///< link-local address of port forwarding interface
    };
 
    /** DNS info */
    structure DnsInfo {
        vector<string>          serverAddrs;            ///< List of active domain name server addresses
        vector<string>          searchSuffixes;         ///< List of active domain search suffixes
        boolean                 resolverPrefersIPv6;    ///< Resolver should prefer IPv6 addresses
    };
 
    /** Routing info */
    structure RoutingInfo {
        vector<IpRoute>         ipv4Routes;             ///< List of active IPv4 routes
        vector<IpRoute>         ipv6Routes;             ///< List of active IPv6 routes
    };
 
    /** Common info */
    structure CommonInfo {
        DnsInfo                       dns;                    ///< DNS info
        RoutingInfo                   routing;                ///< Routing info
        PortForwardingInfo      portForwarding;         ///< Port forwarding info
    };
 
    /** IP configuration method */
    enumeration IpConfigMethod {
        STATIC,                                         ///< No automatic configuration
        DHCP,                                           ///< Use DHCP for automatic configuration (IPv4 only)
        AUTO                                            ///< Use automatic configuration (IPv6 only)
    };
 
    /** Interface specific IP settings */
    structure InterfaceIpSettings {
        boolean                 enabled;                    ///< Controls if IPv4/IPv6 is enabled
        IpConfigMethod          configMethod;               ///< Interface configuration method
        IpAddrCidr              staticAddrCidr;             ///< Statically assigned IPv4/IPv6 address (CIDR)
        string                  staticDefaultGatewayAddr;   ///< Statically assigned default gateway address
        string                  dhcpPreferredHostname;      ///< Preferred hostname (only used with DHCP)
        boolean                 stablePrivacyEnabled;       ///< Enable RFC7217 stable-privacy addresses (IPv6 only)
    };
 
    /** Interface specific IPv4 info */
    structure InterfaceIPv4Info {
        boolean                 enabled;                ///< \c true if IPv4 is enabled
        IpConfigMethod          configMethod;           ///< Interface configuration method
        vector<IpAddrCidr>      addrsCidr;              ///< List of active IPv4 addresses with prefix length
        string                  dhcpServerAddr;         ///< IPv4 address of DHCP server or empty
        string                  dhcpPreferredHostname;  ///< Preferred hostname (only used with DHCP)
    };
 
    /** Interface specific IPv6 info */
    structure InterfaceIPv6Info {
        boolean                 enabled;                ///< \c true if IPv6 is enabled
        IpConfigMethod          configMethod;           ///< Interface configuration method
        vector<IpAddrCidr>      addrsCidr;              ///< List of active IPv6 addresses with prefix length
        string                  dhcpServerId;           ///< DHCPv6 server id or empty
        string                  dhcpPreferredHostname;  ///< Preferred hostname (only used with DHCP)
        boolean                 raManaged;              ///< "Managed" flag set in router announcements
        boolean                 raOtherConf;            ///< "OtherConf" flag set in router announcements
    };
 
    /** Interface specific settings */
    structure InterfaceSettings {
        boolean                         enabled;        ///< Controls if interface is enabled
        InterfaceIpSettings       ipv4;           ///< Interface specific IPv4 settings
        InterfaceIpSettings       ipv6;           ///< Interface specific IPv6 settings
    };
 
    /** The interface type */
    enumeration InterfaceType {
        ETHERNET,                                       ///< Ethernet interface
        WLAN,                                           ///< WLAN interface
        BRIDGE,                                         ///< Bride interface
        BOND                                            ///< Bond interface
    };
 
    /** Interface operational state */
    enumeration InterfaceOpState {
        NOT_PRESENT,                                    ///< Interface is not present
        DOWN,                                           ///< Interface is down
        NO_LINK,                                        ///< Interface has no link
        UP                                              ///< Interface is up and running
    };
 
    /** Interface specific info */
    structure InterfaceInfo {
        string                  name;                   ///< Internal interface name
        string                  label;                  ///< Interface label (used in user interfaces)
        InterfaceType     type;                   ///< Interface type
        boolean                 enabled;                ///< The dynamic enabled state
        string                  controllingIfName;      ///< Controlling interface (set for bridged interfaces)
        InterfaceOpState        state;                  ///< Operational state of the interface
        string                  macAddr;                ///< MAC address of the interface
        int                     mtu;                    ///< Maximum Transfer Unit (MTU)
        InterfaceIPv4Info       ipv4;                   ///< Interface specific IPv4 info
        InterfaceIPv6Info       ipv6;                   ///< Interface specific IPv6 info
    };
 
    /** EAP outer authentication method */
    enumeration EapOuterAuthMethod {
        EAP_PEAP,                                       ///< PEAP authentication
        EAP_TLS                                         ///< TLS authentication
    };
 
    /** EAP inner authentication method */
    enumeration EapInnerAuthMethod {
        INNER_EAP_MSCHAPv2,                             ///< MSCHAPv2 authentication
        INNER_EAP_TLS                                   ///< TLS authentication
    };
 
    /** EAP authentication status */
    enumeration EapStatus {
        EAP_STATUS_DISABLED,                            ///< EAP authentication disabled
        EAP_STATUS_PENDING,                             ///< EAP authentication pending
        EAP_STATUS_FAILED,                              ///< EAP authentication failed
        EAP_STATUS_SUCCESS                              ///< EAP authentication succeeded
    };
 
    /** EAP authentication settings */
    structure EapAuthSettings {
        string                  identity;               ///< EAP identity
        string                  password;               ///< EAP password (always empty on retrieval!)
        boolean                 clearPassword;          ///< Set to \c true when password should be cleared
        string                  clientCertChain;        ///< client certificate chain
        string                  clientPrivKey;          ///< client private key (always empty on retrieval!)
        boolean                 clearClientPrivKey;     ///< Set to \c true to clear the client private key
        string                  clientPrivKeyPassword;  ///< password of client private key
        EapOuterAuthMethod outerMethod;           ///< Outer authentication method
        EapInnerAuthMethod innerMethod;           ///< Inner authentication method
        string                  caCertChain;            ///< CA certificate chain
        boolean                 forceTrustedCert;       ///< Enforce trusted certificates
        boolean                 allowOffTimeRangeCerts; ///< allow expired and not yet valid TLS certs
        boolean                 allowNotYetValidCertsIfTimeBeforeBuild; ///< allow not yet valid TLS certs if
                                                        ///<   the system time is before the build time
        string                  authServerName;         ///< Name of the RADIUS server (used to verify cert)
    };
 
    /** Ethernet speed */
    enumeration EthSpeed {
        SPEED_AUTO,                                     ///< Use auto-negotiation to set speed
        SPEED_MBIT_10,                                  ///< 10 MBit/s
        SPEED_MBIT_100,                                 ///< 100 MBit/s
        SPEED_MBIT_1000,                                ///< 1000 MBit/s (1 GBit/s)
        SPEED_MBIT_2500                                 ///< 2500 MBit/s (2.5 GBit/s)
    };
 
    /** Ethernet duplex mode */
    enumeration EthDuplexMode {
        DUPLEX_MODE_AUTO,                               ///< Use auto-negotiation to set duplex mode
        DUPLEX_MODE_HALF,                               ///< Half duplex
        DUPLEX_MODE_FULL                                ///< Full duplex
    };
 
    /** Ethernet authentication type */
    enumeration EthAuthType {
        ETH_AUTH_NONE,                                  ///< No authentication
        ETH_AUTH_EAP                                    ///< 802.1x (EAP) authentication
    };
 
    /** Ethernet link mode */
    structure EthLinkMode {
        EthSpeed          speed;                  ///< Interface speed
        EthDuplexMode           duplexMode;             ///< Interface duplex mode
    };
 
    /** Ethernet interface settings */
    structure EthSettings {
        EthLinkMode       linkMode;               ///< Link mode
        int                     mtu;                    ///< Maximum Transfer Unit (MTU)
        EthAuthType             authType;               ///< Authentication type
        EapAuthSettings   eap;                    ///< EAP Settings for 802.1x authentication
        boolean                 lldpEnabled;            ///< \c true if LLDP is enabled
    };
 
    /** Ethernet interface info */
    structure EthInfo {
        EapStatus                 eapStatus;              ///< \c status of EAP authentication
        EthLinkMode         linkMode;               ///< Current link mode
        boolean                   linkModeValid;          ///< \c true if linkMode is valid
        boolean                   autonegEnabled;         ///< \c true if auto-negotiation is enabled
        boolean                   linkDetected;           ///< \c true if a link is detected
        vector<EthLinkMode> supportedLinkModes;   ///< Supported link modes
    };
 
    /** WLAN security protocol */
    enumeration WlanSecProtocol {
        WPA2                                            ///< WPA2 security protocol
    };
 
    /** WLAN authentication type */
    enumeration WlanAuthType {
        WLAN_AUTH_NONE,                                 ///< No authentication
        WLAN_AUTH_PSK,                                  ///< Pre-shared key authentication
        WLAN_AUTH_EAP                                   ///< 802.1x (EAP) authentication
    };
 
    /** WLAN interface settings */
    structure WlanSettings {
        boolean                 enableHT;               ///< Enable high throughput features (802.11n)
        string                  ssid;                   ///< SSID of the wireless network
        string                  bssid;                  ///< BSSID (empty for automatic AP selection)
        int                     mtu;                    ///< Maximum Transfer Unit (MTU)
        WlanSecProtocol         secProtocol;            ///< Security protocol (WPA2)
        WlanAuthType      authType;               ///< Authentication type
        string                  psk;                    ///< Pre-shared key (always empty on retrieval!)
        boolean                 clearPsk;               ///< Set to \c true when PSK should be cleared
        EapAuthSettings   eap;                    ///< EAP Settings for 802.1x authentication
    };
 
    /** WLAN channel width */
    enumeration WlanChannelWidth {
        CHANNEL_WIDTH_UNKNOWN,
        CHANNEL_WIDTH_20_NO_HT,
        CHANNEL_WIDTH_20,
        CHANNEL_WIDTH_40,
        CHANNEL_WIDTH_80,
        CHANNEL_WIDTH_80P80,
        CHANNEL_WIDTH_160
    };
 
    /** WLAN interface info */
    structure WlanInfo {
        boolean                 associated;             ///< \c true if assoiated to an access point
        string                  ssid;                   ///< SSID of the wireless network
        string                  bssid;                  ///< BSSID of associated access point
        int                     channel;                ///< Channel number
        WlanChannelWidth        channelWidth;           ///< Channel width (this is an id and no frequency!)
    };
 
    enumeration DhcpClientIdMode {
        SERIAL_NUMBER,
        MAC_ADDRESS
    };
 
    /** Network settings */
    structure Settings {
        boolean                                 ethFailover;        ///< Automatic failover between ethernet interfaces
        DhcpClientIdMode                        dhcpClientIdMode;   ///< Client ID to send in DHCP responses
        CommonSettings                    common;             ///< Common network settings
        map<string, InterfaceSettings>    ifMap;              ///< Common interface settings
        map<string, EthSettings>          ethMap;             ///< Ethernet specific interface settings
        map<string, WlanSettings>         wlanMap;            ///< WLAN specific interface settings
    };
 
    /** Network info */
    structure Info {
        CommonInfo                        common; ///< Common network info
        map<string, InterfaceInfo>        ifMap;  ///< Common interface info
        map<string, EthInfo>              ethMap; ///< Ethernet specific interface info
        map<string, WlanInfo>                   wlanMap;///< WLAN specific interface info
    };
 
    /** Mapping from application protocol id to name and transport protocol */
    structure PortForwardingProtocolMapping {
        int appProtoId;                                 ///< Application protocol id
        string appProtoName;                            ///< Application protocol name
        string transportProtoName;                      ///< Transport protocol name
    };
 
    /* ---- event definitions ---- */
 
    /** Event that is send when common network info has changed */
    valueobject CommonInfoChangedEvent extends idl.Event {
        CommonInfo commonInfo;                          ///< Current common network info
    };
 
    /** Event that is send when common interface specific network info has changed */
    valueobject InterfaceInfoChangedEvent extends idl.Event {
        InterfaceInfo ifInfo;                     ///< Current common interface specific info
    };
 
    /** Event that is send when ethernet interface specific network info has changed */
    valueobject EthInfoChangedEvent extends idl.Event {
        string ifName;                                  ///< Ethernet interface name
        string ifLabel;                                 ///< interface label
        EthInfo ethInfo;                          ///< Current ethernet interface specific info
    };
 
    /** Event that is send when WLAN interface specific network info has changed */
    valueobject WlanInfoChangedEvent extends idl.Event {
        string ifName;                                  ///< WLAN interface name
        WlanInfo wlanInfo;                              ///< Current WLAN interface specific info
    };
 
    /** Event that is send when the operational state of an interface changed */
    valueobject LinkStateChangedEvent extends idl.Event {
        string ifName;                                  ///< interface name
        string ifLabel;                                 ///< interface label
        InterfaceType ifType;                     ///< interface type
        InterfaceOpState ifState;                       ///< Current operational interface state
    };
 
    /** Event that is send when the presence state of a downstream port forwarding expansion unit changes */
    valueobject PortForwardingExpansionUnitPresenceStateChangedEvent extends idl.Event {
        boolean expansionUnitPresent;                   ///< \c true when an expansion unit is present
    };
 
    /** Event that is sent when a failover between ethernet ports takes place */
    valueobject EthernetFailoverEvent extends idl.Event {
        string ifName;                                  ///< interface name
        string ifLabel;                                 ///< interface label
    };
 
    /** Network configuration interface */
    interface Net {
 
        /** Success code */
        constant int SUCCESS                                    = 0;
 
        /** DNS parameter errors */
        constant int ERR_DNS_TOO_MANY_SERVERS                   = 100;
        constant int ERR_DNS_INVALID_SERVER                     = 101;
        constant int ERR_DNS_TOO_MANY_SEARCH_SUFFIXES           = 102;
        constant int ERR_DNS_INVALID_SEARCH_SUFFIX              = 103;
 
        /** routing parameter errors */
        constant int ERR_ROUTING_IPV4_INVALID_DFLT_GATEWAY_ADDR = 200;
        constant int ERR_ROUTING_IPV6_INVALID_DFLT_GATEWAY_ADDR = 201;
        constant int ERR_ROUTING_IPV4_INVALID_DEST_ADDR         = 202;
        constant int ERR_ROUTING_IPV6_INVALID_DEST_ADDR         = 203;
        constant int ERR_ROUTING_IPV4_INVALID_DEST_PREFIX_LEN   = 204;
        constant int ERR_ROUTING_IPV6_INVALID_DEST_PREFIX_LEN   = 205;
        constant int ERR_ROUTING_IPV4_INVALID_NEXTHOP_ADDR      = 206;
        constant int ERR_ROUTING_IPV6_INVALID_NEXTHOP_ADDR      = 207;
        constant int ERR_ROUTING_IPV4_INVALID_INTERFACE         = 208;
        constant int ERR_ROUTING_IPV6_INVALID_INTERFACE         = 209;
        constant int ERR_ROUTING_IPV4_DEST_IS_NO_NETWORK_ADDR   = 210;
        constant int ERR_ROUTING_IPV6_DEST_IS_NO_NETWORK_ADDR   = 211;
        constant int ERR_ROUTING_IPV4_DEST_IS_DUPLICATE         = 212;
        constant int ERR_ROUTING_IPV6_DEST_IS_DUPLICATE         = 213;
        constant int ERR_ROUTING_IPV4_NO_NEXTHOP_OR_INTERFACE   = 214;
        constant int ERR_ROUTING_IPV6_NO_NEXTHOP_OR_INTERFACE   = 215;
        constant int ERR_ROUTING_IPV4_NEXTHOP_AND_INTERFACE_SET = 216;
        constant int ERR_ROUTING_IPV6_NEXTHOP_AND_INTERFACE_SET = 217;
 
        /** port forwarding parameter errors */
        constant int ERR_PF_INVALID_PRIMARY_UNIT_DOWNSTREAM_INTERFACE = 300;
        constant int ERR_PF_NO_WORKING_PRIMARY_UNIT_UPSTREAM_INTERFACE= 301;
        constant int ERR_PF_NOT_SUPPORTED                             = 302;
 
        /** interface common parameter errors */
        constant int ERR_IF_IPV4_INVALID_CONFIG_METHOD          = 400;
        constant int ERR_IF_IPV6_INVALID_CONFIG_METHOD          = 401;
        constant int ERR_IF_IPV4_INVALID_STATIC_ADDR            = 402;
        constant int ERR_IF_IPV6_INVALID_STATIC_ADDR            = 403;
        constant int ERR_IF_IPV4_INVALID_STATIC_PREFIX_LEN      = 404;
        constant int ERR_IF_IPV6_INVALID_STATIC_PREFIX_LEN      = 405;
        constant int ERR_IF_IPV4_INVALID_DHCP_PREF_HOSTNAME     = 406;
        constant int ERR_IF_IPV6_INVALID_DHCP_PREF_HOSTNAME     = 407;
        constant int ERR_IF_EAP_INVALID_IDENTITY                = 408;
        constant int ERR_IF_EAP_INVALID_PASSWORD                = 409;
        constant int ERR_IF_EAP_INVALID_CLIENT_CERT             = 410;
        constant int ERR_IF_EAP_INVALID_CLIENT_PRIV_KEY_OR_PWD  = 411;
        constant int ERR_IF_EAP_CLIENT_CERT_PRIV_KEY_MISMATCH   = 412;
        constant int ERR_IF_EAP_INVALID_CA_CERT                 = 413;
        constant int ERR_IF_EAP_CA_CERT_VERIFY_FAILED           = 414; /* not used anymore */
        constant int ERR_IF_EAP_INVALID_AUTH_SERVER_NAME        = 415;
 
        /** Ethernet interface parameter errors */
        constant int ERR_ETH_IF_UNSUPPORTED_LINKMODE            = 500;
        constant int ERR_ETH_IF_INVALID_MTU                     = 501;
 
        /** WLAN interface parameter errors */
        constant int ERR_WLAN_IF_INVALID_SSID                   = 600;
        constant int ERR_WLAN_IF_INVALID_BSSID                  = 601;
        constant int ERR_WLAN_IF_INVALID_PSK                    = 602;
        constant int ERR_WLAN_IF_INVALID_MTU                    = 603;
        constant int ERR_WLAN_IF_NOT_SUPPORTED                  = 604;
 
        /** BRIDGE interface parameter errors */
        constant int ERR_BRIDGE_IF_NOT_SUPPORTED                = 700;
 
        /**
         * Retrieve information about all network interfaces.
         *
         * @return Current network information
         */
        Info getInfo();
 
        /**
         * Retrieve the current network interface settings.
         *
         * @return Settings for all supported network interfaces
         */
        Settings getSettings();
 
        /**
         * Update the network interface settings.
         *
         * @param settings  New network settings
         *
         * @return 0 if OK
         * @return non-zero in case of error (see error constants above)
         */
        int setSettings(in Settings settings);
 
        /**
         * Retrieve the list of port forwarding protocol mappings.
         *
         * @return Port forwarding protocol mappings
         */
        vector<PortForwardingProtocolMapping> getPortForwardingProtocolMappings();
 
    };
 
}