Port SERVICEACCESS - MACSEC¶

Port for opening MACsec-protected connections that can be used by other ports

This port requires a PCAP driver to be installed.

Stimulation¶

This port has no stimulus capabilities.

Properties 🛈¶

Name	Available if	Default value	Valid values	Type	Description
Physical Layer ❲Network Access❳
Network interface card			[ONLINE]	string	The network interface card or network adapter to be used for receiving network packets
MAC address ❲client❳		‘02:00:4C:4F:4F:50’		string	String (format: 02:00:4C:4F:4F:50), ‘default’ if the adapter MAC address should be used
VLAN Settings ❲IEEE 802.1Q❳
VLAN mode		disable	[disable, single tagging]	string	Set to ‘auto’ if the VLAN id from the database should be used, ‘disable’ if no VLAN should be used or ‘single tagging’ if a fixed VLAN id should be specified
VLAN id	VLAN mode: ‘single tagging’	0		int	If incoming packets have a VLAN tag, they will be filtered and only packets having this VLAN id will pass. Incoming packets without any VLAN tag will also pass the filter.
Settings for MACsec Key Agreement ❲MKA❳
Connectivity Association Key ❲CAK❳				string	Key for the MACsec key agreement as a hex string (128 or 256 bits).
Connectivity Association Key Name ❲CKN❳				string	Text which identifies the CAK, as a hex string (8 to 256 bits).
Algorithms for MACsec protocol		‘[GCM-AES-XPN-256, GCM-AES-256, GCM-AES-XPN-128, GCM-AES-128]’		string	List of supported MACsec algorithms. Syntax and a list of all supported algorithms can be found in the help file (Tool tracetronic: Ethernet).
Cycle time MKA [ms]		500		int	Temporal separation between two transmitted MKPDUs in milliseconds (default value: 500 ms, as specified in IEEE 802.1X-2020 section 9.10 NOTE 2)
Do not stop MKA		☐		bool	MKA stays active beyond test case execution.

Jobs 🛈¶

GetMacSecValues¶

Determines the current values for SCI, AN, SAK and CipherSuite which may change e.g. when the remote party causes a new SAK creation. If these values are not yet available, an empty dictionary will be returned.

Return value

Name	Available if	Default value	Valid values	Type	Description
result				object	Dictionary containing the determined values for SCI, AN, SAK and CipherSuite. For XPN algorithms also XPN Salt and XPN SCI List are returned.

RekeyMacSec¶

Triggers a new SAK to be generated. As a key server, a new SAK is generated and distributed. Otherwise, the selection of a new member identifier forces the key server to generate and distribute a new SAK. If no SAK could be distributed or received by the specified timeout, the return value is an empty dictionary. The MKA protocol remains active in the background. The “GetMacSecValues” job can be used to react to subsequent connection parameter changes in the test case, such as the receipt of a new SAK.

Parameter

Name	Available if	Default value	Valid values	Type	Description
Timeout		5.0		float	Timeout in seconds

Return value

Name	Available if	Default value	Valid values	Type	Description
result				object	Dictionary containing the determined values for SCI, AN, SAK and CipherSuite. For XPN algorithms also XPN Salt and XPN SCI List are returned.

ShutdownMacSec¶

Closes the MACsec session

StartMacSecManipulation¶

Asynchronously starts the MACsec header custom manipulation mode (s. Header Manipulation). Valid values for the MACsec header bits are None = no manipulation, 0 = bit not set, and 1 = bit set. Parameters with the suffix “flags” are not MACsec header bits. They are used to determine the type of manipulation. The valid values for this are in the parameter-specific description.

Parameter

Name	Valid values	Type	Description
AN		int	SecTag: Association Number
C	[False, True]	bool	SecTag-TCI: Changed Text Bit: is to be used in combination with E. See IEEE Std 802.1AE 2018
E	[False, True]	bool	SecTag-TCI: Encryption Bit: 0 - none, 1 - payload encrypted
ES	[False, True]	bool	SecTag-TCI: End Station Bit
ICVFlags		int	SecTag: ICV Flags: None = no manipulation, 1 = make ICV invalid
PNFlags		int	SecTag: Packet Number Flags: None = PNStart is absolute, 1 = PNStart is relative to current PN
PNStart		int	SecTag: Packet Number Start is applied once after StartMacSecManipulation. See PNFlags.
PNStep		int	SecTag: Packet Number Step is applied to each subsequent packet after the initial packet.
SC	[False, True]	bool	SecTag-TCI: Secure Channel Identifier included in SecTAG
SCB	[False, True]	bool	SecTag-TCI: Single Copy Broadcast Capability Bit
SCI		ByteStream	SecTag: Secure Channel Identifier
SL		int	SecTag: Short Length
V	[False, True]	bool	SecTag-TCI: Version Bit
VlanId		int	ID with which VLAN packets should be tagged. None = VLAN ID is not applied.

StartMkaManipulation¶

Starts manipulation of outgoing MKPDUs (s. MKA-Manipulation).

Parameter

Name	Available if	Default value	Valid values	Type	Description
Manipulator				object	A ByteStream or user-defined manipulation object that is dynamically applied to MKA packets to be sent (s. MKA-Manipulation).

StartupMacSec¶

Establishes a MACsec-secured connection with the remote party. If this is not successful within the specified timeout, an empty dictionary is returned. The MKA protocol remains active in the background. The “GetMacSecValues” job can be used to react to subsequent connection parameter changes in the test case, such as the receipt of a new SAK.

Parameter

Name	Default value	Valid values	Type	Description
Cak			object	Key for the MACsec key agreement as a hex string (128 or 256 bits). None will default to the TBC option.
Ckn			object	Text which identifies the CAK, as a hex string (8 to 256 bits). None will default to the TBC option.
KeyServerFlag	True	[False, True]	bool	True: enable key server capability, False: another MKA participant is to be key server
KeyServerPrio	1		int	Priority from 0 (high) to 255 (low) with which the key server role should be perceived if KeyServerFlag=True
MkaAlgorithms			object	List of supported MACsec algorithms. Syntax and a list of all supported algorithms can be found in the help file (Tool tracetronic: Ethernet). None will default to the TBC option.
MkaCycleTime	500		int	Temporal separation between two transmitted MKPDUs in milliseconds (default value: 500 ms, as specified in IEEE 802.1X-2020 section 9.10 NOTE 2)
Timeout	5.0		float	Time (in seconds) to wait until MACsec has been activated

Return value

Name	Available if	Default value	Valid values	Type	Description
result				object	Dictionary containing the determined values for SCI, AN, SAK and CipherSuite. For XPN algorithms also XPN Salt and XPN SCI List are returned.

StopMacSecManipulation¶

Asynchronously stops the MACsec header custom manipulation mode (s. Header Manipulation).

StopMkaManipulation¶

Stops manipulation of outgoing MKPDUs (s. MKA-Manipulation).