#include "include/jmacsecsa.h"
Detailed Description
MACsec Security Association
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.
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
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
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
The encoding of the MACsec EtherType in the MPDU is illustrated in the next figure
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.
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.
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
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
| Tag Type | Name | Value |
|---|---|---|
| Customer VLAN Tag | IEEE 802.1Q Tag Protocol EtherType (802.1QTagType) | 81-00 |
| Service or Backbone VLAN Tag | IEEE 802.1Q Tag Protocol EtherType (802.1QSTagType) | 88-A8 |
| Backbone Service Instance Tag | IEEE 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
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
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
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
- The SA Key (SAK)
- The SCI for the SC used by the SecY to transmit
- The PN
- The SecTAG
- The sequence of octets that compose the User Data
e. Receives the following parameters from the Cipher Suite protection operation
- The sequence of octets that compose the Secure Data
- 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
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
- The SA Key (SAK)
- The SCI for the SC used by the SecY to transmit
- The PN
- The SecTAG
- The sequence of octets that compose the Secure Data
- The ICV
h. Receives the following parameters from the Cipher Suite validation operation
- A Valid indication, if the integrity check was valid and the User Data could be recovered
- The sequence of octets that compose the User Data
i. Updates the replay check (see IEEE Std 802.1AE-2006 Section 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)
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
For API Documentation:
- See also
- ProtocolPP::jmacsec
- ProtocolPP::jmacsecsa
- ProtocolPP::jprotocol
- ProtocolPP::jmodes
- ProtocolPP::jarray
- ProtocolPP::jrand
- ProtocolPP::jenum
For Additional Documentation:
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:
- include/jmacsecsa.h
