Protocol++® (Protocolpp®)  v5.6.2
jmacsec Class Reference

#include "include/jmacsec.h"

Detailed Description

MACsec protocol

Information provided by IEEE https://standards.ieee.org/getieee802/download/802.1AE-2006.pdf

Encoding of MACsec protocol data units

This clause specifies the structure and encoding of the MACsec Protocol Data Units (MPDUs) exchanged between MAC Security Entities (SecYs). It

  • Specifies rules for the representation and encoding of protocol fields
  • Specifies the major components of each MPDU, and the fields they comprise
  • Reviews the purpose of each field, and the functionality provided
  • Specifies validation of the MPDU on reception
  • Documents the allocation of an EtherType value, the MACsec EtherType, to identify MPDUs

NOTE—The MPDU validation checks specified in this clause are deliberately limited to ensuring successful decoding, and do not overlap with the specification of SecY operation (Clause 10).

Structure, representation, and encoding

All MPDUs shall contain an integral number of octets. The octets in a MPDU are numbered starting from 1 and increasing in the order they are put into the MAC Service Data Unit (MSDU) that accompanies a request to or indication from the instance of the MAC Internal Sublayer Service (ISS) used by a SecY. The bits in an octet are numbered from 1 to 8 in order of increasing bit significance, where 1 is the least significant bit in the octet. Where octets and bits within a MPDU are represented using a diagram, octets shown higher on the page than subsequent octets and octets shown to the left of subsequent octets at the same height on the page are lower numbered, bits shown to the left of other bits within the same octet are higher numbered. Where two or more consecutive octets are represented as hexadecimal values, lower numbered octet(s) are shown to the left and each octet following the first is preceded by a hyphen, e.g., 01-80-C2-00-00-00.

When consecutive octets are used to encode a binary number, the lower octet number has the more significant value. When consecutive bits within an octet are used to encode a binary number, the higher bit number has the most significant value. When bits within consecutive octets are used to encode a binary number, the lower octet number composes the more significant bits of the number. A flag is encoded as a single bit, and is set (True) if the bit takes the value 1, and clear (False) otherwise. The remaining bits within the octet can be used to encode other protocol fields.

Security Encapsulation of Ethernet Packets (MacSec)

Major components

Each MPDU comprises

  • A Security TAG (SecTAG)
  • Secure Data (9.10) c) An Integrity Check Value (ICV)

Each of these components comprises an integral number of octets and is encoded in successive octets of the MPDU as illustrated in Figure 9-1

NOTE—The MPDU does not include the source and destination MAC addresses, as these are separate parameters of the service requests and indications to and from the insecure service that supports MACsec

Packet Data Unit (PDU) for MacSec

Security TAG

The Security TAG (SecTAG) is identified by the MACsec EtherType, and conveys the

  • TAG Control Information (TCI, 9.5)
  • Association Number (AN, 9.6)
  • Short Length (SL, 9.7)
  • Packet Number (PN, 9.8)
  • Optionally encoded Secure Channel Identifier (SCI, 9.9).

The format of the SecTAG is illustrated in Figure 9-2

Security Tag (SecTag) for MacSec packets

MACsec EtherType

The MACsec EtherType comprises octet 1 and octet 2 of the SecTAG. It is included to allow

  • Coexistence of MACsec capable systems in the same environment as other systems
  • Incremental deployment of MACsec capable systems
  • Peer SecYs to communicate using the same media as other communicating entities
  • Concurrent operation of Key Agreement protocols that are independent of the MACsec protocol and the Current Cipher Suite
  • Operation of other protocols and entities that make use of the service provided by the SecY’s Uncontrolled Port to communicate independently of the Key Agreement state
Ethernet Packet Type

The encoding of the MACsec EtherType in the MPDU is illustrated in the next figure

EtherType Field Within the Macsec Packet

TAG Control Information (TCI)

The TCI field comprises bits 8 through 3 of octet 3 (Figure 9-4) of the SecTAG. These bits facilitate

  • Version numbering of the MACsec protocol without changing the MACsec EtherType
  • Optional use of the MAC Source Address parameter to convey the SCI
  • Optional inclusion of an explicitly encoded SCI (7.1.2, Figure 7-7)
  • Use of the EPON (Clause 12) Single Copy Broadcast capability, without requiring an explicit SCI to distinguish the SCB Secure Channel
  • Extraction of the User Data from MPDUs by systems that do not possess the SAK (8.1.2, 8.1.4) when confidentiality is not being provided
  • Determination of whether confidentiality or integrity alone are in use

The encoding of the MACsec TCI in the MPDU is illustrated in Figure 9-4.

TAG Control Information (TCI) of the Macsec Packet

TCIAN bit encoding is as follows:

  • The version number shall be 0 and is encoded in bit 8. NOTE—Future versions of the MACsec protocol may use additional bits of the TCI to encode the version number. The fields and format of the remainder of the MPDU may change if the version number changes
  • If the MPDU is transmitted by an end station and the first 6 octets of the SCI are equal to the value of the octets of MAC Source Address parameter of the ISS request in canonical format order, bit 7 [the End Station (ES) bit] of the TCI may be set
  • If the ES bit is set, bit 6 (the SC bit) shall not be set and an SCI shall not be explicitly encoded in the SecTAG. The ES bit is clear if the Source Address is not used to determine the SCI. If an SCI (9.9, 7.1.2) is explicitly encoded in the SecTAG, bit 6 (the SC bit) of the TCI shall be set. The SC bit shall be clear if an SCI is not present in the SecTAG
  • If and only if the MPDU is associated with the Secure Channel that supports the EPON Single Copy Broadcast capability, bit 5 (the SCB bit) of the TCI may be set
  • If the SCB is set, bit 6 (the SC bit) shall not be set and an SCI shall not be explicitly included in the SecTAG. If the ES bit is set and the SCB is not set, the SCI comprises a Port Identifier (7.1.2) component of 00-01. If the SCB bit is set, the Port Identifier (7.1.2) component has the reserved SCB value of 00-00
  • If the Encryption (E) bit is set and the Changed Text (C) bit is clear, the frame is not processed by the SecY (10.6) but is reserved for use by the KaY. Otherwise, the E bit is set if and only if confidentiality is being provided and is clear if integrity only is being provided
  • The C bit is clear if and only if the Secure Data is exactly the same as the User Data and the ICV is 16 octets long. When the Default Cipher Suite (14.5) is used for integrity protection only, the Secure Data is the unmodified User Data, and a 16 octet ICV is used. Both the E bit and the C bit are therefore clear, and the data conveyed by MACsec is available to applications, such as network management, that need to see the data but are not trusted with the SAK that would permit its modification. Other Cipher Suites may also integrity protect data without modifying it, and use a 16 octet ICV, enabling read access to the data by other applications. The E and C bits are also clear for such Cipher Suites when integrity only is provided
  • Some cryptographic algorithms modify or add to the data even when integrity only is being provided, or use an ICV that is not 16 octets long. The C bit is never clear for such an algorithm, even if the E bit is clear to indicate that confidentiality is not provided. Recovery of the data from a MACsec frame with the E bit clear and the C bit set requires knowledge of the Cipher Suite at a minimum. That information is not provided in the MACsec frame. If both the C bit and E bit are set, confidentiality of the original User Data is being provided.

Association Number (AN)

The AN is encoded as an integer in bits 1 and 2 of octet 3 of the SecTAG (Figure 9-4) and identifies up to four different SAs within the context of an SC. NOTE—Although each receiving SecY only needs to maintain two SAs per SC, the use of a 2-bit AN simplifies the design of protocols that update values associated with each of the SAs.

Short Length (SL)

SL is an integer encoded in bits 1 through 6 of octet 4 of the SecTAG and is set to the number of octets in the Secure Data (9.10) field, i.e., the number of octets between the last octet of the SecTAG and the first octet of the ICV, if that number is less than 48. Otherwise, SL is set to zero. If the number is zero then the frame is deemed not to have been short. The Secure Data field always comprises at least one octet. Bits 7 and 8 of octet 4 shall be zero.

Packet Number (PN)

The PN is encoded in octets 5 through 8 of the SecTAG to

  • Provide a unique IV PDU for all MPDUs transmitted using the same SA
  • Support replay protection

NOTE—As specified in this clause, the IV used by the default Cipher Suite (GCM-AES-128) comprises the SCI (even if the SCI is not transmitted in the SecTAG) and the PN. Subject to proper unique MAC Address allocation procedures, the SCI is a globally unique identifier for a SecY. To satisfy the IV uniqueness requirements of CTR mode of operation, a fresh key is used before PN values are reused.

Secure Channel Identifier (SCI)

If the SC bit in the TCI is set, the SCI (7.1.2, 8.2.1) is encoded in octets 9 through 16 of the SecTAG, and facilitates

  • Identification of the SA where the CA comprises three or more peers
  • Network management identification of the SecY that has transmitted the frame Octets 9 through 14 of the SecTAG encode the System Identifier component of the SCI. This comprises the six octets of a globally unique MAC address uniquely associated with the transmitting SecY. The octet values and their sequence conform to the Canonical Format specified by IEEE Std 802. Octets 15 and 16 of the SecTAG encode the Port Identifier component of the SCI, as an integer.

NOTE —The 64-bit value FF-FF-FF-FF-FF-FF is never used as an SCI and is reserved for use by implementations to indicate the absence of an SC or an SCI in contexts where an SC can be present.

An explicitly encoded SCI field in the SecTAG is not required on point-to-point links, which are identified by the operPointToPointMAC status parameter of the service provider. In the point-to-point case, the secure association created by the SecY for the peer SecYs, together with the direction of transmission of the secured MPDU, can be used to identify the transmitting SecY and therefore an explicitly encoded SCI is unnecessary. Although the SCI does not have to be repeated in each frame when only two SecYs participate in a CA (see Clause 8, Clause9, and Clause10), the SCI still forms part of the cryptographic computation.

Secure Data

The Secure Data comprises all the octets that follow the MACsec TAG and precede the ICV. The Secure Data field is never of zero length, since the primitives of the MAC Service require a non-null MSDU (User Data) parameter.

NOTE 1—In practice, if the MSDU composed by the operation of the current Cipher Suite following MPDU reception contains less than two octets, it will be discarded by the user of the SecY’s controlled port, since it is too short to contain an EtherType or an LLC length field. Such discard is, however, determined by the user of the Controlled Port and not by the SecY itself.

NOTE 2—Ethernet transports frames of a minimum size, and provides no explicit indication of PDU length if the PDU is composed of fewer octets. The SL field allows the originator of the frame, which is not necessarily aware of the need of an intervening Ethernet component to pad the frame, to specify the number of octets in the MPDU, thus allowing the receiver to unambiguously locate the ICV.

Integrity Check Value (ICV)

The length of the ICV is Cipher Suite dependent, but is not less than 8 octets and not more than 16 octets, depending on the Cipher Suite.

NOTE—The ICV protects the destination and source MAC address parameters, as well as all the fields of the MPDU.

PDU validation

A received MPDU is valid if and only if it comprises a valid SecTAG, one or more octets of Secure Data, and an ICV, i.e.,

  • It comprises at least 17 octets
  • Octets 1 and 2 compose the MACsec EtherType
  • The V bit in the TCI is clear
  • If the ES or the SCB bit in the TCI is set, then the SC bit is clear
  • Bits 7 and 8 of octet 4 of the SecTAG are clear
  • If the C and SC bits in the TCI are clear, the MPDU comprises 24 octets plus the number of octets indicated by the SL field if that is non-zero and at least 72 octets otherwise
  • If the C bit is clear and the SC bit set, then the MPDU comprises 32 octets plus the number of octets indicated by the SL field if that is non-zero and at least 80 octets otherwise
  • If the C bit is set and the SC bit clear, then the MPDU comprises 8 octets plus the minimum length of the ICV as determined by the Cipher Suite in use at the receiving SecY, plus the number of octets indicated by the SL field if that is non-zero and at least 48 additional octets otherwise
  • If the C and SC bits are both set, the frame comprises at least 16 octets plus the minimum length of the ICV as determined by the Cipher Suite in use at the receiving SecY, plus the number of octets indicated by the SL field if that is non-zero and at least 48 additional octets otherwise

802.1Q VLAN Tagging

Tagging a frame with a VLAN tag

a. Allows a VID to be conveyed, facilitating consistent VLAN classification of the frame throughout the network and enabling segregation of frames assigned to different VIDs

b. Allows priority (IEEE Std 802.1AC, 6.8) to be conveyed with the frame when using IEEE 802 LAN media access control methods that provide no inherent capability to signal priority

Tag Format

Each tag comprises the following sequential information elements:

a. A Tag Protocol Identifier (TPID)

b. Tag Control Information (TCI) that is dependent on the tag type

c. Additional information, if and as required by the tag type and TCI

VLAN Tag Format

The tag encoding function supports each EISS (6.8) instance by using an instance of the ISS to transmit and receive frames and encodes the above information in the first and subsequent octets of the MSDU that will accompany an ISS M_UNITDATA.request, immediately prior to encoding the sequence of octets that constitute the corresponding EISS M_UNITDATA.request’s MSDU. On reception the tag decoding function is selected by the TPID and decodes the TCI and additional information octets (if present) prior to issuing an EISS M_UNITDATA.indication with an MSDU that comprises the subsequent octets

The following types of tags are specified:

a. A C-TAG, for general use by C-VLAN Bridges and C-VLAN components of Provider Edge Bridges

b. An S-TAG, reserved for use by S-VLAN Bridges, the S-VLAN component of Provider Edge Bridges and BEBs, and C-VLAN Bridges signaling priority to a PBN or a PBBN

c. An I-TAG, reserved for use by BEBs

NOTE—The S-TAG is identical to the B-TAG

A distinct EtherType has been allocated (see table below) for use in the TPID field of each tag type so they can be distinguished from each other, and from other protocols

IEEE 802.1Q Ethertype allocations
Tag TypeNameValue
Customer VLAN TagIEEE 802.1Q Tag Protocol EtherType (802.1QTagType)81-00
Service or Backbone VLAN TagIEEE 802.1Q Tag Protocol EtherType (802.1QSTagType)88-A8
Backbone Service Instance TagIEEE 802.1Q Backbone Service Instance Tag EtherType (802.1QITagType)88-E7

VLAN Tag Control Information (TCI)

The VLAN TCI field is two octets in length and encodes the vlan_identifier, drop eligible, and priority parameters of the corresponding EISS M_UNITDATA.request as unsigned binary numbers

VLAN TCI Format

The VID is encoded in a 12-bit field. A VLAN Bride may not support the full range of VID values but shall support the use of all VID values in the range 0 through a maximum N, less than or equal to 4094 and specified for that implementation. The following table identifies VID values that have specific meanings or uses

Reserved VID values

NOTE 1 - There is a distinction between the range of VIDs that an implementation can support and the maximum number of active VIDs supported at any one time. An implementation supports only 16 active VIDs, for example, may use VIDs chosen from anywhere in the identifier space, or from a limited range. The latter can result in difficulties where different Bridges in the same network support different maximums. It is recommended that new implementations of this standard support the full range of VIDs, even if the number of active VIDs is limited

The priority and drop eligible parameters are conveyed in the 3-bit PCP field and the DEI field

NOTE 2 - Previous versions of this standard used bit 5 of octet 1 of the TCI in C-TAGs as a Canonical Format Indicator (CFI). Bridges conformant to this version of the standard will not interoperate with Bridges that set the CFI as a result of inserting C-TAGs in frames received from an IEEE 802.5 Token Ring LAN. Bridges conformant to this version of the standard will interoperate with Bridges that forward bit 5 of octet 1 as a CFI but do not 802.5 Token Ring interfaces

Support for double tags

When using a single VLAN tag, the tag in the security association name VLANTAG1 will be used. If a second tag is used, the tag in the security association named VLANTAG2 will be inserted between VLANTAG1 and the EthType of the packet as shown below

VLAN Double Tag Formatting

Packet Processing

Secure frame generation

For each transmit request at the Controlled Port, the Secure Frame Generation process

a. Assigns the frame to an SA (10.5.1)

b. Assigns the nextPN variable for that SA to be used as the value of the PN in the SecTAG (10.5.2)

c. Encodes the octets of the SecTAG (10.5.3)

d. Provides the protection function (14.1, 10.5.4) of the Current Cipher Suite with

  1. The SA Key (SAK)
  2. The SCI for the SC used by the SecY to transmit
  3. The PN
  4. The SecTAG
  5. The sequence of octets that compose the User Data

e. Receives the following parameters from the Cipher Suite protection operation

  1. The sequence of octets that compose the Secure Data
  2. The ICV

f. Issues a request to the Transmit Multiplexer with the destination and source MAC addresses, and priority of the frame as received from the Controlled Port, and an MPDU comprising the octets of the SecTAG, Secure Data, and the ICV concatenated in that order (10.5.5)

If the management control protectFrames is False, the preceding steps are omitted, an identical transmit request is made to the Transmit Multiplexer, and the OutPktsUntagged counter incremented

NOTE—This model of operation supports the externally observable behavior that can result when the Cipher Suite implementation calculates the Secure Data and ICV parameters for a number of frames in parallel, and the responses to protection and validation requests are delayed. Transmitted frames are not misordered

Transmit SA assignment

Each SA is identified by its Association Number (AN). Each frame is assigned to the SA identified by the current value of the encodingSA variable. This is updated following an LMI request from the KaY to start transmitting using the SA and can be read but not written by network management. Frames will be protected using the encodingSA immediately after the last frame assigned to the previous SA has been protected.

If the SA identified by the encodingSA is not available for use, and the management control protectFrames is set, MAC_Operational transitions to False for the Controlled Port, and frames are neither accepted or delivered using the port

Transmit PN assignment

The frame’s PN is set to the value of nextPN for the SA, and nextPN is incremented. If the nextPN variable for the encodingSA is zero (or 2 32 ) and the protectFrames control is set, MAC_Operational transitions to False for the Controlled Port and frames are neither accepted or delivered. The initial value of nextPN is set by the KaY via the LMI prior to use of the SA, and its current value can be read both while and after the SA is used to transmit frames. The value of nextPN can be read, but not written, by network management.

SecTAG encoding

The SecTAG is encoded as specified in Clause 9

  • If the management control useES is True and alwaysIncludeSCI is False, the ES bit in the SecTAG shall be set. Otherwise, if useES is False or alwaysIncludeSCI is True, the ES bit shall be clear.
  • If the management control alwaysIncludeSCI is set, or the number of receive SCs with SAs enabled for reception is greater than one and both useES and useSCB are False, the SC bit in the SecTAG shall be set and the SCI explicitly encoded in the SecTAG; otherwise, the SC bit shall be clear and the SCI not explicitly encoded
  • If the management control useSCB is True and alwaysIncludeSCI is False, the SCB bit in the SecTAG shall be set. Otherwise, if useSCB is False or alwaysIncludeSCI is True, the SCB bit shall be clear
  • The values of useES, useSCB, and alwaysIncludeSCI can be written and read by management. The number of active receive SCs is controlled by the KaY but can be read by management
  • If a frame is to be integrity protected, but not encrypted, with the number and value of the octets of the Secure Data exactly the same as those of the User Data, and an ICV of 16 octets, then the E bit shall be clear and the C bit clear. The E bit shall be clear and the C bit set if the frame is not encrypted but the octets of the Secure Data differ from those of the User Data or the ICV is not 16 octets
  • If both confidentiality (through encryption) and integrity protection are applied to a frame then both the E bit and the C bit shall be set. The SecY shall not encode a SecTAG that has both the E bit set and the C bit clear for any frame received from the Controlled Port for transmission
  • If the alwaysIncludeSCI control is set or the number of receive SCs with SAs enabled for reception is greater than 1, the SCI is included in the SecTAG; otherwise, it is omitted. The value of alwaysIncludeSCI can be written and read by management. The number of active receive SCs is controlled by the KaY, but can be read by management

Cryptographic protection

If the Cipher Suite is currently protecting frames using the previous SA and its SA Key, as reflected by the value of the encipheringSA, the frame can be queued awaiting protection. The value of the encipheringSA is updated, and protection of the frame parameters is started within a minimum frame size transmission delay, after the last frame has been protected using the previous key

The use of each of the Cipher Suites specified by this standard is specified in Clause 14, which takes precedence over any explanation in this or other clauses

The appropriate octet counter is incremented by the number of octets in the User Data (OutOctetsEncrypted if confidentiality protection was provided, and OutOctetsProtected otherwise)

Transmit request

If the MPDU composed of the concatenated octets of the SecTAG, Secure Data, and ICV exceeds the size of the MSDU supported by the Common Port, the frame is discarded and a counter incremented. Details of the discarded frame may be recorded to assist network management resolution of the problem. Otherwise, the parameters of the service request are submitted to the Transmit Multiplexer

Receive Secure frame verification

For each receive indication from the Receive Demultiplexer, the Secure Frame Verification process

a. Examines the user data for a SecTAG

b. Validates frames with a SecTAG as specified in 9.12

c. Extracts and decodes the SecTAG as specified in 9.3 through 9.9

d. Extracts the User Data and ICV as specified in 9.10 and 9.11

e. Assigns the frame to an SA (10.6.1)

f. Performs a preliminary replay check against the last validated PN for the SA (10.6.2)

g. Provides the validation function (14.1, 10.6.3) of the Current Cipher Suite with

  1. The SA Key (SAK)
  2. The SCI for the SC used by the SecY to transmit
  3. The PN
  4. The SecTAG
  5. The sequence of octets that compose the Secure Data
  6. The ICV

h. Receives the following parameters from the Cipher Suite validation operation

  1. A Valid indication, if the integrity check was valid and the User Data could be recovered
  2. The sequence of octets that compose the User Data

i. Updates the replay check (10.6.4)

j. Issues an indication to the Controlled Port with the DA, SA, and priority of the frame as received from the Receive Demultiplexer, and the User Data provided by the validation operation (10.6.5).

If the management control validateFrames is not Strict, frames without a SecTAG are received, counted, and delivered to the Controlled Port; otherwise, they are counted and discarded. If validateFrames is Disabled, cryptographic validation is not applied to tagged frames, but frames whose original service user data can be recovered are delivered. Frames with a SecTAG that has the TCI E bit set but the C bit clear are discarded, as this reserved encoding is used to identify frames with a SecTAG that are not to be delivered to the Controlled Port. Figure 10-5 summarizes the operation of management controls and counters

Receive SA assignment

An SCI is associated with the received frame, and used to locate the receive SC. If an SCI is not explicitly encoded in the SecTAG, the default value established by the KaY for a single peer is used. If the SC is not found, it may be recorded to assist network management resolution of the problem, and:

a. If validateFrames is Strict or the C bit in the SecTAG is set, the InPktsNoSCI counter is incremented and the frame is discarded; otherwise

b. The InPktsUnknownSCI counter is incremented and the frame (with the SecTAG and ICV removed) is delivered to the Controlled Port

If the receive SC has been identified, the frame’s AN is used to locate the receive SA received frame and processing continues with the preliminary replay check. If the SA is not in use:

c. If validateFrames is Strict or the C bit is set, the frame is discarded and the InPktsNotUsingSA counter incremented; otherwise

d. The InPktsUnusedSA counter is incremented and the frame delivered to the Controlled Port

NOTE—The short phrase “the frame is discarded” is commonly used to express the more formal notion of not processing a service primitive (an indication or request) further and recovering the resources that embody the parameters of that service primitive. No further processing is applied. However, if a duplicate of the primitive has been submitted to another process, by the Receive Demultiplexer in this case, processing of that duplicate is unaffected

Preliminary replay check

If replayProtect control is enabled and the PN of the received frame is less than the lowest acceptable packet number (see 10.6.5) for the SA, the frame is discarded and the InPktsLate counter incremented.

NOTE—If the SC is supported by a network that includes buffering with priority queueing, such as a provider bridged network, delivered frames can be reordered.

Cryptographic validation

The frame can be queued awaiting validation. If the frame reception rate exceeds the Cipher Suite’s validation capabilities, the frame may be discarded and the InPktsOverrun counter incremented

If the validateFrames control is Disabled, the Cipher Suite validation is not used to validate the frame

If validateFrames is not Disabled, and the E bit in the SecTAG is set, the Cipher Suite is used to validate and decrypt the frame. If the Cipher Suite does not provide confidentiality protection, it shall not return VALID

The InOctetsDecrypted counter is incremented by the number of octets in the resulting User Data (or an estimate of that number, if VALID is not returned)

If validateFrames is not Disabled, and the E bit in the SecTAG is clear, the Cipher Suite is used to validate the frame. If the Cipher Suite does not provide integrity protection without confidentiality it shall not return VALID. The InOctetsValidated counter is incremented by the number of octets in the resulting User Data (or an estimate of that number, if VALID is not returned)

The frame is marked valid if the Cipher Suite is used and returns VALID, and is marked invalid otherwise. The use of each of the Cipher Suites specified by this standard is specified in Clause 14, which takes precedence over any explanation in this or other clauses

Replay check update

If the PN of the received frame is less than the lowest acceptable packet number for the SA, and replayProtect is enabled, the frame is discarded and the InPktsLate counter incremented.

NOTE—This model of operation assumes that any queuing within the verification process occurs prior to frame validation, and the check described uses the lowest acceptable PN updated by prior frames as described below (10.6.5). Implementations can process frames as convenient, provided the externally observable result is the same.

Receive indication

If the received frame is marked as invalid, and the validateFrames control is Strict or the C bit in the SecTAG was set, the frame is discarded and the InPktsNotValid counter incremented. Otherwise the frame is delivered to the Controlled Port, and the appropriate counter incremented as follows:

a. If the frame is not valid and validateFrames is set to Check, InPktsInvalid, otherwise

b. If the received PN is less than the lowest acceptable PN (treating a PN value of zero as 2 32 ), InPktsDelayed, otherwise

c. If the frame is not valid, InPktsUnchecked, otherwise

d. InPktsOK

If the PN for the frame was equal to or greater than the nextPN variable for the SA, nextPN is set to the value for the received frame, incremented by one. The lowest acceptable PN variable is set to the greater of its existing value and the value of nextPN minus the replayWindow variable.

NOTE—The lowest acceptable packet number can also be set or incremented by the KaY to ensure timely delivery.

Cipher Suites

A Cipher Suite is an interoperable specification of cryptographic algorithms together with the values of parameters (for example, key size) to be used by those algorithms. Specification of the cryptographic functions required by MAC Security in terms of Cipher Suites increases interoperability by providing a clear default and a limited number of alternatives.

This clause specifies

  • Terms that describe the use of each Cipher Suite by the MAC Security Entity (SecY)
  • Capabilities required of each Cipher Suite
  • Requirements this standard places on Cipher Suite specification
  • Mandatory and optional Cipher Suites for use in conjunction with this standard
  • Criteria for the use of additional Cipher Suites in conjunction with MAC Security for implementations for which a claim of conformance to this standard is made

NOTE —The choice and combination of cryptographic methods is notorious for the introduction of unexpected security exposures. Each Cipher Suite is an algorithm or combination of algorithms whose interactions have been studied by the professional security community

Cipher Suite use

A Cipher Suite is initialized with one or more Cipher Suite dependent keys, and then used to protect protocol parameters. Any implementation of the same Cipher Suite, initialized with the same key values, can be used to validate and recover the protected parameters. The protect and validate operations are illustrated in Figure 14-1, and their inputs and outputs specified below

Supported MacSec Ciphersuites

The SAK (Secure Association Key, 3.36, 7.1) is the value of the Cipher Suite dependent key(s)

The SCI (Secure Channel Identifier, 3.36, 7.1.2) is a 64-bit identifier that is globally unique amongst all correctly configured Cipher Suite implementation instances protecting MACsec protocol parameters

The PN (Packet Number, 3.27, 8.3) is a 32-bit number that is never zero, is incremented each time a protect request is made for a given SCI, and is never repeated for an SCI unless the SAK is changed

The Destination Address and Source Address are the MAC addresses of the frame. MAC Addresses are specified as octet strings, using the canonical format specified in IEEE Std 802

The SecTAG is as specified in Clause 9

The ICV (Integrity Check Value, 3.13, 8.3) is a string of octets. VALID is a Boolean parameter. If TRUE the validation was successful

Given the SAK, SCI, PN, Source Address, Destination Address, SecTAG, and the User Data, the Protect operation returns the Secure Data and ICV.

Given the same SAK, SCI, PN, Source Address, Destination Address, and SecTAG, and the Secure Data and ICV, the Verify operation returns the original User Data and VALID. If any of the parameters were modified, VALID is returned False.

Cipher Suite capabilities

Any Cipher Suite used with MACsec shall

  • Provide integrity protection for the SCI, PN, Source Address, Destination Address, SecTAG, and from 0 through ${2}^{16}-1$ octets of User Data on each invocation
  • Provide integrity and confidentiality (if specified) for up to ${2}^{32}-1$ invocations, each with a different PN, without requiring a fresh SAK
  • Given any specific number of octets of User Data, generate a predictable number of octets of Secure Data and ICV

and may

  • Provide confidentiality protection for all the octets of the User Data
  • Provide confidentiality protection for all the octets of the User Data following an initial number of octets, as specified in 10.7.24

and shall not

  • Generate Secure Data that when added to the number of octets in the ICV contains over 896 octets more than the User Data. NOTE — A Cipher Suite may introduce additional fields into the Secure Data even if confidentiality is not provided
  • Modify or constrain the values of the SCI, PN, Source Address, Destination Address, or SecTAG fields, other than as specified in this Clause (14)
  • Require an SAK exceeding 1024 bits long (in total for all keys that compose the SAK)
  • Require different keys for the protect and validate operations

An implementation of MACsec for which conformance to this standard is claimed includes at least one Cipher Suite that provides integrity without confidentiality, with the Secure Data the same as the User Data, and the ICV comprising 16 octets. This requirement is met by the mandatory Default Cipher Suite.

Cipher Suite specification

Each Cipher Suite specification shall comprise an interoperable specification of the protection and verification procedures in terms of the parameters specified in 14.1 and shall state

  • Whether confidentiality of the User Data is provided
  • The maximum difference in the lengths of the User Data and Secure Data
  • The length of the ICV
  • The length and properties of the keys required, including assumptions of the scope of uniqueness

NOTE—While this standard provides definitive specifications of the Cipher Suites that support full conformance, those specifications make the greatest possible use of other public and established standards, and are principally concerned with ensuring unambiguous application of those standards in the context of MAC Security.

Cipher Suite conformance

An implementation of MAC Security that claims full conformance to this standard shall implement the mandatory Cipher Suites in Table 14-1, may implement one or more of the Optional Cipher Suites in the table, and shall not implement any other Cipher Suite. Every conformant implementation shall include at least one Cipher Suite that does not encrypt User Data.

Macsec Ciphersuite Conformance Requirements

NOTE —Currently, Table 14-1 does not include any optional Cipher Suites.

Table 14-1 assigns a Cipher Suite reference number for use in protocol identification within a MACsec context, provides a short name for use in this standard, indicates the type of cryptographic algorithm used and the security services provided, specifies whether the Cipher Suite is mandatory or optional for conformance to this standard, and references the clause of this standard that provides the definitive description of the Cipher Suite.

Conformance with Cipher Suite variance

An implementation of MAC Security that claims conformance to this standard with Cipher Suite variance, shall implement the mandatory Cipher Suites in Table 14-1, may implement one or more of the optional Cipher Suites in Table 14-1, and may implement alternate Cipher Suites that meet the requirements of 14.2 and 14.3, and the following guidelines, and shall not implement any other Cipher Suite, or other combination of cryptographic algorithms and parameters.

The use of additional Cipher Suites shall meet the following guidelines:

  • Algorithms chosen have an effective key length of at least 128 bits. In schemes built on block ciphers, the underlying block cipher has a block width of at least 128 bits
  • If serviced by separate algorithms, the properties of the authentication and confidentiality mechanisms are combinable in accordance with well-established security results. Either the encryption happens before authentication, or the encryption is performed through keystream generation
  • Either of the following holds true:
    • The underlying cryptographic cipher is approved by either a national or international standards body or a government agency; or
    • The following conditions i) through iv) apply:
      • The Cipher Suite provides message authentication using a message authentication algorithm with a publicly available proof of security against forgery attacks, even in a model where the attacker has the ability to choose messages for the sender
      • If confidentiality is provided, the confidentiality mechanism has a publicly available proof of security in a model where the attacker has the ability to adaptively choose both plaintext and cipher text
      • Mechanisms for confidentiality and message authentication are used in a way that is consistent with their proof of security. For example, if using the Cipher Block Chaining (AES-CBC) mode of operation the IV is performed through keystream generation
      • Mechanisms for confidentiality and message authentication are used in a way that is consistent with their proof of security. For instance, if using the Cipher Block Chaining (AES-CBC) mode of operation, the IV is randomly selected with each message, and not sequentially

Default Cipher Suite (GCM–AES–128)

The Default Cipher Suite uses the Galois/Counter Mode of Operation with the AES-128 symmetric block cipher, as specified in this clause by reference to the terms K, IV, A, P, C, T used in section 2.1 of the GCM specification (GCM) as submitted to NIST.

K is the 128 bit SAK. The 64 most significant bits of the 96-bit IV are the octets of the SCI, encoded as a binary number (9.1). The 32 least significant bits of the 96-bit IV are the octets of the PN, encoded as a binary number (9.1). T is the ICV and is 128 bits long. When the bit-strings A, P, and C are specified in terms of octet strings, earlier octets compose earlier bits, and more significant bits in each octet are earlier.

NOTE—The bit strings obtained by transforming MAC Address and data octets using these rules do not correspond to IEEE 802.3 “wire order” for frame transmission.

When the Default Cipher Suite is used for Integrity Protection

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG and User Data concatenated in that order
  • P is null
  • The Secure Data is the octets of the User Data, without modification.

When the Default Cipher Suite is used for Confidentiality Protection without a confidentiality offset

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG concatenated in that order
  • P is the octets of the User Data
  • The Secure Data is C.

When the Default Cipher Suite is used for Confidentiality Protection with a confidentiality offset

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG and the first confidentialityOffset (10.7.24) octets of the User Data concatenated in that order
  • P is the remaining octets of the User Data
  • The Secure Data is the first confidentialityOffset octets of the User Data concatenated with C, in that order.

Media Access Control (MAC) Security–Amendment 2: Extended Packet Numbering

Amendment 2: Extended Packet Numbering

This amendment to IEEE Std 802.1AE-2006 allows more than ${2}^{32}$ MACsec protected frames to be sent using a single Secure Association Key (SAK) by enabling the use of a 64-bit Packet Number (PN) and specifying two Cipher Suites (GCM-AES-XPN-128 and GCM-AES-XPN-256) that use that extended packet numbering as part of their Initial Value (IV) construction. MACsec frame formats and principles of MAC Security Entity operation remain unchanged. Changes are applied to the base text of IEEE Std 802.1AE-2006 as amended by IEEE Std 802.1AEbn-2011

Security TAG

Security Tag Format for Extended Packet Numbers

Packet Number (PN)

The 32 least significant bits of the PN is are encoded in octets 5 through 8 of the SecTAG to

  • Provide a unique IV PDU for all MPDUs transmitted using the same SA
  • Support replay protection

NOTE 1 — As specified in this clause, the IV used by the default Cipher Suite (GCM-AES-128) comprises the SCI (even if the SCI is not transmitted in the SecTAG) and the a 32-bit PN. Subject to proper unique MAC Address allocation procedures, the SCI is a globally unique identifier for a SecY. To satisfy the IV uniqueness requirements of CTR mode of operation, a fresh key is used before PN values are reused

NOTE 2 — If the Current Cipher Suite provides extended packet numbering, i.e. uses a 64-bit PN, the 32 least significant bits of the PN are conveyed in this SecTAG field and the 32 most significant bits are recovered on receipt as specified in 10.6. The IV used by such a Cipher Suite (e.g. GCM-AES-XPN-128, 14.7) comprises a 32-bit SSCI distributed by key agreement protocol and unique for each SCI within the scope of the CA (and hence within potential users of the same SAK) and the 64-bit non-repeating PN

PN recovery and preliminary replay check

If the Current Cipher Suite does not use extended packet numbering, i.e. the PN comprises 32-bits, the value of the PN is that of the lower 32 bits decoded from the SecTAG of the received frame. If extended packet numbering is used, the 32 most significant bits are recovered for each received frame as specified in by applying the assumption that they have remained unchanged since their use in the frame with the lowest acceptable PN (10.6.2) — unless the most significant of the 32 least significant bits of the lowest acceptable PN is set and the corresponding bit of the received PN is not set, in which case the 32 most significant bits of the PN are those of the lowest acceptable PN incremented by one

NOTE—If a large number of successive frames were to be lost ( ${2}^{30}-1$ , corresponding to approximately 9 seconds of full utilization of a 400 Gb/s link by minimum sized Ethernet frames) subsequent receipt of MACsec frames might fail to establish a correct PN value. MKA, the MACsec Key Agreement protocol specified in IEEE Std 802.1X and its amendments communicates the value of the high order bits periodically to recover from this eventuality

verification controls

If the Current Cipher Suite uses extended packet numbering, i.e. a 64-bit PN, then the maximum value of replayWindow used in the Secure Frame Verification process (10.6) is ${2}^{30}–1$, but any higher value set by network management is retained for possible subsequent use with a different Cipher Suite and will be reported if read by network management. This provision provides compatibility with prior revisions of this standard, though it is unlikely that such a high value of replayWindow would have been used

Receive SA creation

A receive SA is created for an existing SC on request from the KaY, with the following parameters:

  • The association number, AN, for the SA
  • nextPN (10.6, 10.6.5)
  • lowestPN, the lowest acceptable PN value for a received frame (10.6, 10.6.2, 10.6.4, 10.6.5)
  • A reference to an SAK that is unchanged for the life of the SA

and, if the Current Cipher Suite uses extended packet numbering (e.g. 14.7, 14.8), the following parameter:

  • an SSCI, unique within all the SecY’s (each associated with a KaY, and identified by an SCI) using the SAK, and subsequently available for Cipher Suite protection and validation operations

Transmit SA creation

An SA is created for the transmit SC on request from the KaY, with the following parameters:

  • AN, the association number for the SA
  • nextPN, the initial value of Transmit PN (10.5.2) for the SA
  • confidentiality, True if the SA is to provide confidentiality as well as integrity for transmitted frames
  • A reference to an SAK that is unchanged for the life of the SA

and, if the Current Cipher Suite uses extended packet numbering(e.g. 14.7, 14.8), the following parameter:

  • an SSCI, unique within all the SecY’s (each associated with a KaY, and identified by an SCI) using the SAK, and subsequently available for Cipher Suite protection and validation operations

SAK creation

An SAK record is created on request from the KaY, with the following parameters:

  • The SAK value
  • A Key Identifier, used by network management to reference the key

and, if the Current Cipher Suite uses extended packet numbering, the following parameter:

  • Salt, a 96-bit parameter subsequently available for Cipher Suite protection and validation operations

Cipher Suite use

The PN (Packet Number, 3.27, 8.3) is a 32-bit number that is never zero, is incremented each time a protect request is made for a given SCI, and is never repeated for an SCI unless the SAK is changed. The size of the PN depends on the Cipher Suite, and is 32-bits unless otherwise specified. Cipher suites that provide extended packet numbering use a 64-bit PN. Irrespective of the size of the PN, only the least significant 32- bits are conveyed in the SecTAG. If extended packet numbering is used, the most significant 32-bits are recovered for each received frame as specified in 10.6.2.

Cipher Suite conformance

Ciphersuites for Macsec Extended Packet Number Packets

GCM–AES–256

GCM-AES-256 uses the Galois/Counter Mode of operation with the AES-256 symmetric block cipher, as specified in this clause by reference to the terms K, IV, A, P, C, T used in NIST SP 800-38D. K is the 256 bit SAK. The 64 most significant bits of the 96-bit IV are the octets of the SCI, encoded as a binary number (9.1). The 32 least significant bits of the 96-bit IV are the octets of the PN, encoded as a binary number (9.1). T is the ICV, and is 128 bits long. When the bit-strings A, P, and C are specified in terms of octet strings, earlier octets compose earlier bits, and more significant bits in each octet are earlier

NOTE — The bit strings obtained by transforming MAC Address and data octets using these rules do not correspond to 802.3 'wire order' for frame transmission.

When the Default Cipher Suite is used for Integrity Protection

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG and User Data concatenated in that order
  • P is null
  • The Secure Data is the octets of the User Data, without modification

When the Default this Cipher Suite is used for Confidentiality Protection without a confidentiality offset

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG concatenated in that order
  • P is the octets of the User Data
  • The Secure Data is C

When the Default this Cipher Suite is used for Confidentiality Protection with a confidentiality offset

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG and the first confidentialityOffset (10.7.24) octets of the User Data concatenated in that order
  • P is the remaining octets of the User Data
  • The Secure Data is the first confidentialityOffset octets of the User Data concatenated with C, in that order

GCM–AES–XPN-128

Each instance of the GCM-AES-XPN-128 Cipher Suite, i.e. the protection and validation capabilities created for a given SAK at the request of the KaY (10.7.26, Figure 10-6) maintains an instance of the following parameter as specified in 10.7.23:

  • Salt, a 96-bit value distributed by key agreement protocol to all members of the CA.

The MACsec Key Agreement (MKA) protocol specified in IEEE 802.1X-2010 does not include explicit parameters for distributing the Salt (applicable to all SAs using a given SAK) or the SSCI (applicable to a given SA, using a given SAK) explicitly. Each KaY computes these parameters from the MKA protocol information as follows. The 64 least-significant bits of the Salt comprise the SCI of the MKA Key Server, and the 32 most significant bits of the Salt comprise the value obtain by the exclusive-or of the 32 most significant and the 32 least significant bits of that SCI. The KaY with numerically greatest SCI uses the SSCI value 0x0001, the KaY with the next to the greatest SCI uses the SSCI value 0x0002, and so on

NOTE 1 — This procedure does not ensure that the Salt is secret. Readers of this standard are encouraged to consult the latest revision of 802.1X and its amendments

NOTE 2 — MKA guarantees that each KaY that receives a given SAK has a unique SCI, and these SCIs are present in every MKPDU that conveys a (key-wrapped) SAK

GCM-AES-XPN-128 uses the Galois/Counter Mode of operation with the AES-128 symmetric block cipher, as specified in this clause by reference to the terms K, IV, A, P, C, T used in NIST SP 800-38D. K is the 128 bit SAK. The 32 most significant bits of the 96-bit IV are the octets of the SSCI, encoded as a binary number (9.1) and exclusive-or’d with the 32 most significant bits of the Salt. The 64 least significant bits of the 96-bit IV are the octets of the PN, encoded as a binary number (9.1) and exclusive-or’d with the 64 least significant bits of the Salt. T is the ICV, and is 128 bits long. When the bit-strings A, P, and C are specified in terms of octet strings, earlier octets compose earlier bits, and more significant bits in each octet are earlier

NOTE 3 — The bit strings obtained by transforming MAC Address and data octets using these rules do not correspond to 802.3 'wire order' for frame transmission

When this Cipher Suite is used for Integrity Protection

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG and User Data concatenated in that order
  • P is null
  • The Secure Data is the octets of the User Data, without modification

When this Cipher Suite is used for Confidentiality Protection without a confidentiality offset

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG concatenated in that order
  • P is the octets of the User Data
  • The Secure Data is C

This Cipher Suite does not provide Confidentiality Protection with a confidentiality offset

GCM–AES–XPN-256

Each instance of the GCM-AES-XPN-256 Cipher Suite, i.e. the protection and validation capabilities created for a given SAK at the request of the KaY (10.7.26, Figure 10-6) maintains an instance of the following parameter as specified in 10.7.23:

  • Salt, a 96-bit value distributed by key agreement protocol to all members of the CA

The MACsec Key Agreement (MKA) protocol specified in IEEE 802.1X-2010 does not include explicit parameters for distributing the Salt (applicable to all SAs using a given SAK) or the SSCI (applicable to a given SA, using a given SAK) explicitly. Each KaY computes these parameters from the MKA protocol information as follows. The 64 least-significant bits of the Salt comprise the SCI of the MKA Key Server, and the 32 most significant bits of the Salt comprise the value obtain by the exclusive-or of the 32 most significant and the 32 least significant bits of that SCI. The KaY with numerically greatest SCI uses the SSCI value 0x0001, the KaY with the next to the greatest SCI uses the SSCI value 0x0002, and so on

NOTE 1 — This procedure does not ensure that the Salt is secret. Readers of this standard are encouraged to consult the latest revision of 802.1X and its amendments

NOTE 2 — MKA guarantees that each KaY that receives a given SAK has a unique SCI, and these SCIs are present in every MKPDU that conveys a (key-wrapped) SAK

GCM-AES-XPN-256 uses the Galois/Counter Mode of operation with the AES-256 symmetric block cipher, as specified in this clause by reference to the terms K, IV, A, P, C, T used in NIST SP 800-38D

K is the 256 bit SAK. The 32 most significant bits of the 96-bit IV are the octets of the SSCI, encoded as a binary number (9.1) and exclusive-or’d with the 32 most significant bits of the Salt. The 64 least significant bits of the 96-bit IV are the octets of the PN, encoded as a binary number (9.1) and exclusive-or’d with the 64 least significant bits of the Salt. T is the ICV, and is 128 bits long. When the bit-strings A, P, and C are specified in terms of octet strings, earlier octets compose earlier bits, and more significant bits in each octet are earlier

NOTE 3 — The bit strings obtained by transforming MAC Address and data octets using these rules do not correspond to 802.3 'wire order' for frame transmission

When this Cipher Suite is used for Integrity Protection

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG and User Data concatenated in that order.
  • P is null
  • The Secure Data is the octets of the User Data, without modification

When this Cipher Suite is used for Confidentiality Protection without a confidentiality offset

  • A is the Destination MAC Address, Source MAC Address, and the octets of the SecTAG concatenated in that order
  • P is the octets of the User Data
  • The Secure Data is C

This Cipher Suite does not provide Confidentiality Protection with a confidentiality offset

For API Documentation:

See also
ProtocolPP::jmacsec
ProtocolPP::jmacsecsa
ProtocolPP::jprotocol
ProtocolPP::jmodes
ProtocolPP::jarray
ProtocolPP::jrand
ProtocolPP::jenum

For Additional Documentation:

See also
jmacsec
jmacsecsa
jprotocol
jmodes
jarray
jrand
jenum
Protocol++® (ProtocolPP®) written by : John Peter Greninger • © John Peter Greninger 2015-2024 • All Rights Reserved
All copyrights and trademarks are the property of their respective owners

The source code contained or described herein and all documents related to the source code (herein called "Material") are owned by John Peter Greninger and Sheila Rocha Greninger. Title to the Material remains with John Peter Greninger and Sheila Rocha Greninger. The Material contains trade secrets and proprietary and confidential information of John Peter Greninger and Sheila Rocha Greninger. The Material is protected by worldwide copyright and trade secret laws and treaty provisions. No part of the Material may be used, copied, reproduced, modified, published, uploaded, posted, transmitted, distributed, or disclosed in any way without prior express written consent of John Peter Greninger and Sheila Rocha Greninger (both are required)

No license under any patent, copyright, trade secret, or other intellectual property right is granted to or conferred upon you by disclosure or delivery of the Materials, either expressly, by implication, inducement, estoppel, or otherwise. Any license under such intellectual property rights must be express and approved by John Peter Greninger and Sheila Rocha Greninger in writing

Licensing information can be found at www.protocolpp.com/license with use of the binary forms permitted provided that the following conditions are met:

  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution
  • Any and all modifications must be returned to John Peter Greninger at GitHub.com https://github.com/jpgreninger/protocolpp for evaluation. Inclusion of modifications in the source code shall be determined solely by John Peter Greninger. Failure to provide modifications shall render this license NULL and VOID and revoke any rights to use of Protocol++®
  • Commercial use (incidental or not) requires a fee-based license obtainable at www.protocolpp.com/shop
  • Academic or research use requires prior written and notarized permission from John Peter and Sheila Rocha Greninger

Use of the source code requires purchase of the source code. Source code can be purchased at www.protocolpp.com/shop

  • US Copyrights at https://www.copyright.gov/
    • TXu002059872 (Version 1.0.0)
    • TXu002066632 (Version 1.2.7)
    • TXu002082674 (Version 1.4.0)
    • TXu002097880 (Version 2.0.0)
    • TXu002169236 (Version 3.0.1)
    • TXu002182417 (Version 4.0.0)
    • TXu002219402 (Version 5.0.0)
    • TXu002272076 (Version 5.2.1)
    • TXu002383571 (Version 5.4.3)

The name of its contributor may not be used to endorse or promote products derived from this software without specific prior written permission and licensing

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTOR "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE

The documentation for this class was generated from the following file: