RFC 4535
GSAKMP: Group Secure Association Key Management Protocol
GSAKMP: Group Secure Association Key Management Protocol 🦋
Part 1 of 23 💖
RFC 4535, published in June 2006 📅
Authors: H. Harney, U. Meth, A. Colegrove (all at SPARTA, Inc.), and G. Gross (IdentAware) 👯♀️
Category: Standards Track 👑. This is an Internet standards track protocol, so it's an official spec and not just an idea someone had 💅
Obsoletes / Updates: The title block doesn't list anything this RFC obsoletes or updates 🙈
Stream: Network Working Group ✨
Status of This Memo ✨
Okay so this doc is an Internet standards track protocol for the whole Internet community 🌐 It's also asking everyone to talk about it and send suggestions for making it better 💬 If you want the official standardization state and status of this protocol, check the current edition of the "Internet Official Protocol Standards" (STD 1) 📚 And good news, distribution of this memo is unlimited, so share it with everyone 🫶
Copyright Notice 🌸
Copyright (C) The Internet Society (2006). 💜
Abstract 🔥
Here's the tea ☕ This document specifies the Group Secure Association Key Management Protocol, also known as GSAKMP 🦋 Basically, GSAKMP gives you a whole security framework for creating and managing cryptographic groups on a network, and it's giving main character energy 👑
Some of the iconic things it does:
- It disseminates group policy and authenticates users 🪪
- It has rules for making access control decisions during group establishment and recovery 🚪
- It can recover from the compromise of group members 🛟
- It lets you delegate group security functions 🧚
- It has capabilities to destroy the group 💀
And it also generates group keys 🔑 Obsessed, honestly 😭
Table of Contents 🧚
1. Introduction ....................................................7
1.1. GSAKMP Overview ............................................7
1.2. Document Organization ......................................9
2. Terminology .....................................................9
3. Security Considerations ........................................12
3.1. Security Assumptions ......................................12
3.2. Related Protocols .........................................13
3.2.1. ISAKMP .............................................13
3.2.2. FIPS Pub 196 .......................................13
3.2.3. LKH ................................................13
3.2.4. Diffie-Hellman .....................................14
3.3. Denial of Service (DoS) Attack ............................14
3.4. Rekey Availability ........................................14
3.5. Proof of Trust Hierarchy ..................................15
4. Architecture ...................................................15
4.1. Trust Model ...............................................15
4.1.1. Components .........................................15
4.1.2. GO .................................................16
4.1.3. GC/KS ..............................................16
4.1.4. Subordinate GC/KS ..................................17
4.1.5. GM .................................................17
4.1.6. Assumptions ........................................18
4.2. Rule-Based Security Policy ................................18
4.2.1. Access Control .....................................19
4.2.2. Authorizations for Security-Relevant Actions .......20
4.3. Distributed Operation .....................................20
4.4. Concept of Operation ......................................22
4.4.1. Assumptions ........................................22
4.4.2. Creation of a Policy Token .........................22
4.4.3. Creation of a Group ................................23
4.4.4. Discovery of GC/KS .................................24
4.4.5. GC/KS Registration Policy Enforcement ..............24
4.4.6. GM Registration Policy Enforcement .................24
4.4.7. Autonomous Distributed GSAKMP Operations ...........24
5. Group Life Cycle ...............................................27
5.1. Group Definition ..........................................27
5.2. Group Establishment .......................................27
5.2.1. Standard Group Establishment .......................28
5.2.1.1. Request to Join ...........................30
5.2.1.2. Key Download ..............................31
5.2.1.3. Request to Join Error .....................33
5.2.1.4. Key Download - Ack/Failure ................34
5.2.1.5. Lack of Ack ...............................35
5.2.2. Cookies: Group Establishment with Denial of
Service Protection .................................36
5.2.3. Group Establishment for Receive-Only Members .......39
5.3. Group Maintenance .........................................39
5.3.1. Group Management ...................................39
5.3.1.1. Rekey Events ..............................39
5.3.1.2. Policy Updates ............................40
5.3.1.3. Group Destruction .........................40
5.3.2. Leaving a Group ....................................41
5.3.2.1. Eviction ..................................41
5.3.2.2. Voluntary Departure without Notice ........41
5.3.2.3. De-Registration ...........................41
5.3.2.3.1. Request to Depart ..............41
5.3.2.3.2. Departure_Response .............43
5.3.2.3.3. Departure_ACK ..................44
6. Security Suite .................................................45
6.1. Assumptions ...............................................45
6.2. Definition Suite 1 ........................................45
7. GSAKMP Payload Structure .......................................47
7.1. GSAKMP Header .............................................47
7.1.1. GSAKMP Header Structure ............................47
7.1.1.1. GroupID Structure .........................51
7.1.1.1.1. UTF-8 ..........................51
7.1.1.1.2. Octet String ...................52
7.1.1.1.3. IPv4 Group Identifier ..........52
7.1.1.1.4. IPv6 Group Identifier ..........53
7.1.2. GSAKMP Header Processing ...........................53
7.2. Generic Payload Header ....................................55
7.2.1. Generic Payload Header Structure ...................55
7.2.2. Generic Payload Header Processing ..................56
7.3. Policy Token Payload ......................................56
7.3.1. Policy Token Payload Structure .....................56
7.3.2. Policy Token Payload Processing ....................57
7.4. Key Download Payload ......................................58
7.4.1. Key Download Payload Structure .....................58
7.4.1.1. Key Datum Structure .......................61
7.4.1.2. Rekey Array Structure .....................63
7.4.2. Key Download Payload Processing ....................63
7.5. Rekey Event Payload .......................................64
7.5.1. Rekey Event Payload Structure ......................64
7.5.1.1. Rekey Event Header Structure .............66
7.5.1.2. Rekey Event Data Structure ...............67
7.5.1.2.1. Key Package Structure ..........68
7.5.2. Rekey Event Payload Processing .....................69
7.6. Identification Payload ....................................71
7.6.1. Identification Payload Structure ...................71
7.6.1.1. ID_U_NAME Structure .......................74
7.6.2. Identification Payload Processing ..................74
7.6.2.1. ID_U_NAME Processing ......................75
7.7. Certificate Payload .......................................75
7.7.1. Certificate Payload Structure ......................75
7.7.2. Certificate Payload Processing .....................77
7.8. Signature Payload .........................................78
7.8.1. Signature Payload Structure ........................78
7.8.2. Signature Payload Processing .......................80
7.9. Notification Payload ......................................81
7.9.1. Notification Payload Structure .....................81
7.9.1.1. Notification Data - Acknowledgement
(ACK) Payload Type ........................83
7.9.1.2. Notification Data -
Cookie_Required and Cookie Payload Type ...83
7.9.1.3. Notification Data - Mechanism
Choices Payload Type ......................84
7.9.1.4. Notification Data - IPv4 and IPv6
Value Payload Types .......................85
7.9.2. Notification Payload Processing ....................85
7.10. Vendor ID Payload ........................................86
7.10.1. Vendor ID Payload Structure .......................86
7.10.2. Vendor ID Payload Processing ......................87
7.11. Key Creation Payload .....................................88
7.11.1. Key Creation Payload Structure ....................88
7.11.2. Key Creation Payload Processing ...................89
7.12. Nonce Payload ............................................90
7.12.1. Nonce Payload Structure ...........................90
7.12.2. Nonce Payload Processing ..........................91
8. GSAKMP State Diagram ...........................................92
9. IANA Considerations ............................................95
9.1. IANA Port Number Assignment ...............................95
9.2. Initial IANA Registry Contents ............................95
10. Acknowledgements ..............................................96
11. References ....................................................97
11.1. Normative References .....................................97
11.2. Informative References ...................................98
Appendix A. LKH Information ......................................100
A.1. LKH Overview .............................................100
A.2. LKH and GSAKMP ...........................................101
A.3. LKH Examples .............................................102
A.3.1. LKH Key Download Example ..........................102
A.3.2. LKH Rekey Event Example ..........................103List of Figures 🎀
1 GSAKMP Ladder Diagram .........................................28
2 GSAKMP Ladder Diagram with Cookies ............................37
3 GSAKMP Header Format ..........................................47
4 GroupID UTF-8 Format ..........................................51
5 GroupID Octet String Format ...................................52
6 GroupID IPv4 Format ...........................................52
7 GroupID IPv6 Format ...........................................53
8 Generic Payload Header ........................................55
9 Policy Token Payload Format ...................................56
10 Key Download Payload Format ...................................58
11 Key Download Data Item Format .................................59
12 Key Datum Format ..............................................61
13 Rekey Array Structure Format ..................................63
14 Rekey Event Payload Format ....................................64
15 Rekey Event Header Format .....................................66
16 Rekey Event Data Format .......................................68
17 Key Package Format ............................................68
18 Identification Payload Format .................................72
19 Unencoded Name (ID-U-NAME) Format .............................74
20 Certificate Payload Format ....................................76
21 Signature Payload Format ......................................78
22 Notification Payload Format ...................................81
23 Notification Data - Acknowledge Payload Type Format ...........83
24 Notification Data - Mechanism Choices Payload Type Format......84
25 Vendor ID Payload Format ......................................86
26 Key Creation Payload Format ...................................88
27 Nonce Payload Format ..........................................90
28 GSAKMP State Diagram ..........................................92
29 LKH Tree .....................................................100
30 GSAKMP LKH Tree ..............................................101List of Tables 🍓
1 Request to Join (RTJ) Message Definition ......................30
2 Key Download (KeyDL) Message Definition .......................31
3 Request to Join Error (RTJ-Err) Message Definition ............33
4 Key Download - Ack/Failure (KeyDL-A/F) Message Definition .....34
5 Lack of Ack (LOA) Message Definition ..........................35
6 Cookie Download Message Definition ............................37
7 Rekey Event Message Definition ................................40
8 Request_to_Depart (RTD) Message Definition ....................42
9 Departure_Response (DR) Message Definition ....................43
10 Departure_ACK (DA) Message Definition .........................44
11 Group Identification Types ....................................48
12 Payload Types .................................................49
13 Exchange Types ................................................49
14 Policy Token Types ............................................57
15 Key Download Data Item Types ..................................60
16 Cryptographic Key Types .......................................62
17 Rekey Event Types .............................................66
18 Identification Classification .................................72
19 Identification Types ..........................................73
20 Certificate Payload Types .....................................77
21 Signature Types ...............................................79
22 Notification Types ............................................82
23 Acknowledgement Types .........................................83
24 Mechanism Types ...............................................84
25 Nonce Hash Types ..............................................85
26 Types Of Key Creation Information .............................89
27 Nonce Types ...................................................91
28 GSAKMP States .................................................93
29 State Transition Events .......................................941. Introduction ✨
okay so GSAKMP is the protocol that handles policy distribution, policy enforcement, key distribution, and key management for cryptographic groups 🔐 Every group shares a common key (or a set of keys) for data processing, and those keys back up a system-level security policy so the group can be trusted to do its security-relevant stuff 💅
The group needs to be able to do security services, and that requires a Group Secure Association (GSA) to be set up first 🦋 A GSA makes sure everyone has a common "group-level" definition of security policy, plus enforcement of that policy. Distributing the cryptographic keys is a mechanism that runs on top of those group-level policy enforcements, so it's all connected 🧚
1.1. GSAKMP Overview
Protecting group information means you need a security policy, and every participating party has to enforce that policy 🫶 Controlling who gets the cryptographic key is the main way the access control policy gets enforced. So the primary purpose of GSAKMP is to generate a group key and disseminate it in a secure way, no cap 🔥
GSAKMP splits group security management into three major roles: 1) Group Owner, 2) Group Controller Key Server, and 3) Group Member. The Group Owner writes the security policy rules for a group and puts them in the policy token 📜 The Group Controller Key Server (GC/KS) creates and maintains the keys, and it enforces the group policy by granting access to potential Group Members (GMs) according to the policy token 👑 To enforce a group's policy, potential Group Members need to know the group's access control policy, an unambiguous identification of any party downloading keys to them, and verifiable chains of authority for key download. Basically, Group Members need to know who might be in the group, and they need to verify that the key disseminator is actually authorized to act in that capacity 🙈
To establish a Group Secure Association (GSA) for these activities, the identity of each party in the process MUST be unambiguously asserted and authenticated. It MUST also be verified that each party is authorized, as defined by the policy token, to function in his role in the protocol (e.g., GM or GC/KS). No skipping this part, bestie 💀
The security features of the establishment protocol for the GSA include:
- Group policy identification
- Group policy dissemination
- GM to GC/KS SA establishment to protect data
- Access control checking
GSAKMP provides mechanisms for cryptographic group creation and management. Other protocols may be used alongside GSAKMP so that various applications can create functional groups that match their own application-specific requirements 🌸 For example, for a small-scale video conference, the organizer might use a session invitation protocol like SIP [RFC3261] to share the time of the conference, the address of the session, and the formats to be used 🎀 For a large-scale video transmission, the organizer might use a multicast announcement protocol like SAP [RFC2974] instead 📣
This document describes a useful default set of security algorithms and configurations, called Security Suite 1. This suite lets you describe an entire set of algorithms and settings to prospective group members in a concise way, which is giving efficiency 😭 Other security suites MAY be defined as needed and MAY be disseminated during the out-of-band announcement of a group 🦋
Distributed architectures are how you support large-scale cryptographic groups 🌈 Secure distributed architectures need authorized delegation of GSA actions to network resources, and the fully specified policy token is the mechanism that makes this authorization happen. Sending this policy token to all joining GMs lets GSAKMP securely support distributed architectures and multiple data sources, which is so iconic ✨
Many-to-many group communications need multiple data sources. Multiple data sources are supported because the policy token and policy payloads let group members review the group access control and authorization parameters 👀 This member review process gives each member (each potential source of data) the ability to determine whether the group provides adequate protection for their data. Main character energy, honestly 👑
1.2. Document Organization
The rest of this document is organized as follows: Section 2 presents the terminology and concepts used to present the requirements of this protocol. Section 3 outlines the security considerations with respect to GSAKMP. Section 4 defines the architecture of GSAKMP. Section 5 describes the group management life cycle. Section 6 describes the Security Suite Definition. Section 7 presents the message types and formats used during each phase of the life cycle. Section 8 defines the state diagram for the protocol 🧚💜
2. Terminology ✨
okay bestie, let's lock in the vocab 🔒 these terms show up all over this doc, so we need them down cold 💅
Requirements Terminology: the keywords "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT" and "MAY" that show up in this document are to be read the way [RFC2119] describes 🎀
Certificate: a data structure used to verifiably bind an identity to a cryptographic key (e.g., X.509v3) 🔐
Compromise Recovery: the act of recovering a secure operating state after detecting that a group member cannot be trusted 😭 this can be accomplished by rekey 🔄
Cryptographic Group: a set of entities sharing or desiring to share a GSA 🦋
Group Controller Key Server (GC/KS): a group member with authority to perform critical protocol actions, including creating and distributing keys and building and maintaining the rekey structures 👑 as the group evolves, it MAY become desirable to have multiple controllers perform these functions ✨
Group Member (GM): any entity with access to the group keys 🫶 regardless of how a member becomes part of the group or how the group is structured, GMs will perform the following actions:
- Authenticate and validate the identities and the authorizations of entities performing security-relevant actions
- Accept group keys from the GC/KS
- Request group keys from the GC/KS
- Enforce the cooperative group policies as stated in the group policy token
- Perform peer review of key management actions
- Manage local key
Group Owner (GO): the entity authorized for generating and modifying an authenticatable policy token for the group, and for notifying the GC/KS to start the group 🌸
Group Policy: the Group Policy completely describes the protection mechanisms and security-relevant behaviors of the group 🛡️ this policy MUST be commonly understood and enforced by the group for coherent secure operations 💜
Group Secure Association (GSA): a logical association of users or hosts that share cryptographic key(s) 🌈 this group may be established to support associations between applications or communication protocols ✨
Group Traffic Protection Key (GTPK): the key or keys created for protecting the group data 🔑
Key Datum: a single key and its associated attributes for its usage 🍓
Key Encryption Key (KEK): a key used in an encryption mechanism for wrapping another key 🎁
Key Handle: the identifier of a particular instance or version of a key 🏷️
Key ID: the identifier for a key that MUST stay static throughout the life cycle of this key 🪪
Key Package: Type/Length/Data format containing a Key Datum 📦
Logical Key Hierarchy (LKH) Array: the group of keys created to facilitate the LKH compromise recovery methodology 🧚
Policy Token (PT): the policy token is a data structure used to disseminate group policy and the mechanisms to enforce it 📜 it is issued and signed by an authorized Group Owner 🖋️ each member of the group MUST verify the token, meet the group join policy, and enforce the policy of the group (e.g., encrypt application data with a specific algorithm) 💅 the group policy token will contain a variety of information, including:
- GSAKMP protocol version
- Key creation method
- Key dissemination policy
- Access control policy
- Group authorization policy
- Compromise recovery policy
- Data protection mechanisms
Rekey: the act of changing keys within a group as defined by policy 🔄
Rekey Array: the construct that contains all the rekey information for a particular member 🗂️
Rekey Key: the KEK used to encrypt keys for a subset of the group 🗝️
Subordinate Group Controller Key Server (S-GC/KS): any group member having the appropriate processing and trust characteristics, as defined in the group policy, that has the potential to act as a S-GC/KS 🌷 this will allow the group processing and communication requirements to be distributed equitably throughout the network (e.g., distribute group key) 🤝 the optional use of GSAKMP with Subordinate Group Controller Key Servers will be documented in a separate paper 📄
Wrapping KeyID: the Key ID of the key used to wrap a Key Package 🎀
Wrapping Key Handle: the key handle of the key used to wrap the Key Package 🎀
3. Security Considerations
okay, this part is serious, so pay attention 🙈 the security of an implemented GSAKMP system is affected by supporting factors too, not just the spec itself 🔥 these are discussed here 💀
3.1. Security Assumptions
the following assumptions are made as the basis for the security discussion 🧠
- GSAKMP assumes its supporting platform can provide the process and data separation services at the appropriate assurance level to support its groups.
- The key generation function of the cryptographic engine will only generate strong keys.
- The security of this protocol is critically dependent on the randomness of the randomly chosen parameters. These should be generated by a strong random or properly seeded pseudo-random source [RFC4086].
- The security of a group can be affected by the accuracy of the system clock. Therefore, GSAKMP assumes that the system clock is close to correct time. If a GSAKMP host relies on a network time service to set its local clock, then that protocol must be secure against attackers. The maximum allowable clock skew across the group membership is policy configurable, with a default of 5 minutes ⏰
- As described in the message processing section, the use of the nonce value used for freshness along with a signature is the mechanism used to foil replay attacks. In any use of nonces, a core requirement is unpredictability of the nonce, from an attacker's viewpoint. The utility of the nonce relies on the inability of an attacker either to reuse old nonces or to predict the nonce value 🎲
- GSAKMP does not provide identity protection 🙅♀️
- The group's multicast routing infrastructure is not secured by GSAKMP, and therefore it may be possible to create a multicast flooding denial of service attack using the multicast application's data stream. Either an insider (i.e., a rogue GM) or a non-member could direct the multicast routers to spray data at a victim system 🚨
- The compromise of a S-GC/KS forces the re-registration of all GMs under its control. The GM recognizes this situation by finding the S-GC/KS's certificate on a CRL as supplied by a service such as LDAP 😱
- The compromise of the GO forces termination of the group. The GM recognizes this situation by finding the GO's certificate on a Certificate Revocation List (CRL) as supplied by a service such as LDAP 💔
3.2. Related Protocols
GSAKMP derives from two (2) existing protocols: ISAKMP [RFC2408] and FIPS Pub 196 [FIPS196] 🧩 in accordance with Security Suite 1, GSAKMP implementations MUST support the use of Diffie-Hellman key exchange [DH77] for two-party key creation and MAY use Logical Key Hierarchy (LKH) [RFC2627] for rekey capability 🔐 the GSAKMP design was also influenced by the following protocols: [HHMCD01], [RFC2093], [RFC2094], [BMS], and [RFC2412] 📚
3.2.1. ISAKMP
ISAKMP provides a flexible structure of chained payloads in support of authenticated key exchange and security association management for pairwise communications. GSAKMP builds upon these features to provide policy enforcement features in support of diverse group communications 🪜
3.2.2. FIPS Pub 196
FIPS Pub 196 provides a mutual authentication protocol 🤝
3.2.3. LKH
When group policy dictates that a recovery of the group security is necessary after the discovery of the compromise of a GM, then GSAKMP relies upon a rekey capability (i.e., LKH) to enable group recovery after a compromise [RFC2627]. This is optional, since in many instances it may be better to destroy the compromised group and rebuild a secure group 💥➡️🌱
3.2.4. Diffie-Hellman
A Group may rely upon two-party key creation mechanisms, i.e., Diffie-Hellman, to protect sensitive data during download 🔑
The information in this section borrows heavily from [IKEv2], as this protocol has already worked through similar issues and GSAKMP is using the same security considerations for its purposes. This section will contain paraphrased sections of [IKEv2] modified for GSAKMP as appropriate 🫶
The strength of a key derived from a Diffie-Hellman exchange using specific p and g values depends on the inherent strength of the values, the size of the exponent used, and the entropy provided by the random number generator used. A strong random number generator combined with the recommendations from [RFC3526] on Diffie-Hellman exponent size is recommended as sufficient. An implementation should make note of this conservative estimate when establishing policy and negotiating security parameters 🧮
Note that these limitations are on the Diffie-Hellman values themselves. There is nothing in GSAKMP that prohibits using stronger values, nor is there anything that will dilute the strength obtained from stronger values. In fact, the extensible framework of GSAKMP encourages the definition of more Security Suites 🚀
It is assumed that the Diffie-Hellman exponents in this exchange are erased from memory after use. In particular, these exponents MUST NOT be derived from long-lived secrets such as the seed to a pseudo-random generator that is not erased after use 🧹
3.3. Denial of Service (DoS) Attack
This GSAKMP specification addresses the mitigation for a distributed IP spoofing attack (a subset of possible DoS attacks) in Section 5.2.2, "Cookies: Group Establishment with Denial of Service Protection" 🛡️
3.4. Rekey Availability
In addition to GSAKMP's capability to do rekey operations, GSAKMP MUST also have the capability to make this rekey information highly available to GMs 📣 the necessity of GMs receiving rekey messages requires the use of methods to increase the likelihood of receipt of rekey messages. These methods MAY include multiple transmissions of the rekey message, posting of the rekey message on a bulletin board, etc. 📋 compliant GSAKMP implementations supporting the optional rekey capability MUST support retransmission of rekey messages 🔁
3.5. Proof of Trust Hierarchy
As defined by [HCM], security group policy MUST be defined in a verifiable manner. GSAKMP anchors its trust in the creator of the group, the GO 👑
The policy token explicitly defines all the parameters that create a secure verifiable infrastructure. The GSAKMP Policy Token is issued and signed by the GO. The GC/KS will verify it and grant access to GMs only if they meet the rules of the policy token 🎟️ the new GMs will accept access only if 1) the token verifies, 2) the GC/KS is an authorized disseminator, and 3) the group mechanisms are acceptable for protecting the GMs data 🫧
4. Architecture ✨
okay so this section is all about the architecture, and it's giving trust model energy 🦋 It lays out a trust model for GSAKMP plus the concept of operations for building a trusted distributed infrastructure for group key and policy distribution 💖
GSAKMP vibes with the IETF MSEC architectural concepts from the MSEC Architecture document [RFC3740]. It uses the MSEC components to make a trust model for operations that carry out the security principles of mutual suspicion and trusted policy creation authorities. no cap, it's very "trust nobody, verify everything" 🫶
4.1. Trust Model
4.1.1. Components
the trust model has four key components 🎀
- Group Owner (GO),
- Group Controller Key Server (GC/KS),
- Subordinate GC/KS (S-GC/KS), and
- Group Member (GM).
the goal of the GSAKMP trust model is to get trust from one common trusted policy creation authority for a group 👑 every security-relevant decision and action GSAKMP makes has to be traceable back to that authority and verified by it. there are two trusted policy creation authorities for GSAKMP: the GO (the policy creation authority) and the PKI root that lets us verify the GO. iykyk 💅
4.1.2. GO
the GO is the policy creation authority for the group ✨ it has a well-defined identity that matters to the group, and that identity can belong to a person or to a group-trusted component. every potential entity in the group has to recognize the GO as the one with authority to specify policy for the group 🫶
the policy reflects how well the data in a group needs protecting. ultimately, the data and the application environment are what drive the security policy for the group 🌸
the GO has to figure out which security rules and mechanisms fit the data protected by the group keys. all of this info gets captured in a policy token (PT). the GO creates the PT and signs it 💜
4.1.3. GC/KS
the GC/KS is authorized to do a bunch of things: key creation, key distribution, rekey, and group membership management 🔥
as the key creation authority, the GC/KS creates the set of keys for the group. those keys include the Group Traffic Protection Keys (GTPKs) and first-tier rekey keys. there may be second-tier rekey trees if the group needs a distributed rekey management structure 🧚
as the key distribution (registration) authority, it has to tell the group where its registration services are. the GC/KS will have to enforce key access control as part of the key distribution and registration processes 🙈
as the group rekey authority, it performs rekey to change the group's GTPK. changing the GTPK limits the exposure of data encrypted with any single GTPK ⭐
finally, as the group membership management authority, the GC/KS can manage the group membership (registration, eviction, de-registration, etc.). this can be done partly with a key tree approach, like Logical Key Hierarchies (LKH), which is an optional approach 🌈
4.1.4. Subordinate GC/KS
a subordinate GC/KS is used to spread the GC/KS functionality across multiple entities 🦋 the S-GC/KS has all the authorities of the GC/KS except one: it will not create the GTPK. it's assumed here that the group transmits data with a single GTPK at any one time, and that GTPK comes from the GC/KS 💖
note that compared to the GC/KS, the S-GC/KS has an extra security check to handle: the S-GC/KS must register as a member with the GC/KS, and during that process it has to verify the authority of the GC/KS 🔐
4.1.5. GM
the GM has two jobs: make sure all security-relevant actions are authorized, and use the group keys properly 🫶 during registration, the GM verifies that the PT is signed by a recognized GO. it also verifies that the GC/KS or S-GC/KS doing the registration is authorized, as specified in the PT. if rekey and new PTs get distributed to the group, the GM verifies that they're proper and that all actions are authorized ✨
the GM gets access to group data by receiving the group keys, and that comes with a responsibility to protect the key from unauthorized disclosure 👑
GSAKMP doesn't offer any enforcement mechanisms to control which GMs are multicast speakers at a given moment 💅 that policy and its enforcement depend on the multicast application and its protocols. still, GSAKMP does let a group have one of three Group Security Association multicast speaker configurations 🌈
- There is a single GM authorized to be the group's speaker. There is one multicast application SA allocated by the GO in support of that speaker. The PT initializes this multicast application SA and identifies the GM that has been authorized to be speaker. All GMs share a single TPK with that GM speaker. Sequence number checking for anti-replay protection is feasible and enabled by default. This is the default group configuration. GSAKMP implementations MUST support this configuration.
- The GO authorizes all of the GMs to be group speakers. The GO allocates one multicast application SA in support of these speakers. The PT initializes this multicast application SA and indicates that any GM can be a speaker. All of the GMs share a single GTPK and other SA state information. Consequently, some SA security features such as sequence number checking for anti-replay protection cannot be supported by this configuration. GSAKMP implementations MUST support this group configuration.
- The GO authorizes a subset of the GMs to be group speakers (which may be the subset composed of all GMs). The GO allocates a distinct multicast application SA for each of these speakers. The PT identifies the authorized speakers and initializes each of their multicast application Security Associations. The speakers still share a common TPK across their SA, but each speaker has a separate SA state information instance at every peer GM. Consequently, this configuration supports SA security features, such as sequence number checking for anti-replay protection, or source authentication mechanisms that require per-speaker state at the receiver. The drawback of this configuration is that it does not scale to a large number of speakers. GSAKMP implementations MAY support this group configuration.
4.1.6. Assumptions
the assumptions for this trust model are that 🧠
- the GCKS is never compromised,
- the GO is never compromised,
- the PKI, subject to certificate validation, is trustworthy,
- The GO is capable of creating a security policy to meet the demands of the group,
- the compromises of a group member will be detectable and reported to the GO in a trusted manner,
- the subsequent recovery from a compromise will deny inappropriate access to protected data to the compromised member,
- no security-relevant actions depend on a precise network time,
- there are confidentiality, integrity, multicast source authentication, and anti-replay protection mechanisms for all GSAKMP control messages.
4.2. Rule-Based Security Policy
the trust model for GSAKMP revolves around defining and enforcing the security policy 💖 honestly, using the key only matters in a security sense if it actually represents the group security policy being enforced ✨
group operations are super suited to rule-based security policy 🎀 sending data to lots of endpoints often means defining the authorized endpoints by rules. for example, every IETF attendee at a given conference could be defined as one single group 🌸
if the security policy rules are going to be relevant, they must be coupled with validation mechanisms. the core principle here is that the level of trust you can give a security policy is exactly equal to the level of trust you have in the validation mechanism used to prove that policy 🔥 for example, if all IETF attendees are allowed in, they could register their identity from their certificate when they check in to the meetings. that certificate is issued by a trusted policy creation authority (PKI root) that's authorized to identify someone as an IETF attendee. the GO could make admittance rules for the IETF group based on identity certificates issued from trusted PKIs 🧚
in GSAKMP, every security policy rule is coupled with an explicit validation mechanism 💅 for interoperability, GSAKMP requires that its supporting PKI implementations MUST be compliant to RFC 3280 🫶
if a GM's public key certificate is revoked, the entity that issues that revocation SHOULD signal the GO, so the GO can expel that GM 🙈 the method that signals this event to the GO is not standardized by this specification.
a direct mapping of rule to validation mechanism lets you use multiple rules and PKIs to create groups 🌈 this means a GO can define a group security policy that spans multiple PKI domains, each with its own Certificate Authority public key certificate 👑
4.2.1. Access Control
the access control policy for the group keys is equivalent to the access control policy for the multicast application data the keys are protecting 🔐
in a group, each data source is responsible for making sure access to the source's data is appropriate. that means every data source should know the access control policy for the group keys ✨
in the general case, GSAKMP offers a suite of security services to its applications and doesn't prescribe how they use those services 💖
GSAKMP supports creating GSAs with multiple data sources. it also supports architectures where the GC/KS isn't itself a data source. in multiple data source architectures, GSAKMP requires that the access control policy is precisely defined and distributed to each data source 🎀 the reference for this data structure is the GSAKMP Policy Token [RFC4534].
4.2.2. Authorizations for Security-Relevant Actions
a critical part of the GSAKMP trust model is authorizing security-relevant actions 🔥 these include download of group key, rekey, and PT creation and updates. these actions could be used to disrupt the secure group, so all entities in the group must verify that they were instigated by authorized entities within the group 😭
4.3. Distributed Operation 🌸
Okay so scalability is literally a core feature of GSAKMP 💖 Its whole approach to scaling is setting up S-GC/KSes, which lets the system split up the work of setting up and managing really huge groups. Main character energy 👑
Distributed S-GC/KS operations also let local management authorities happen. In very large groups, subordinate enclaves might be the best ones to run their own group membership, because they actually know the group members directly 🫶
Now for the tricky part 😭 One of the biggest issues with distributed operation is figuring out where the security infrastructure lives and which security suite it uses. Lots of group apps with dynamic interactions have to "find" each other before they can even run. Discovering the security infrastructure is just one more piece of info the group needs in order to operate securely ✨
There are several methods for infrastructure discovery:
- Announcements
- Anycast
- Rendezvous points / Registration
One way to share the security infrastructure location is with announcements 📣 SAP is commonly used to announce a new multicast application or service. If an application uses SAP [RFC2974] to announce a service on a multicast channel, that service could be extended to include the security infrastructure location for a particular group.
Announcements can also be used by GSAKMP in one of two modes: expanding ring searches (ERSes) of security infrastructure and ERSes for infrastructure discovery. Either way, GSAKMP would use a multicast broadcast that slowly grows its range by adding multicast hops, like a little ripple spreading out 🌊 The multicast source controls the packet's multicast range by explicitly setting its Time To Live count.
An expanding ring announcement works like this: the GC/KS announces that it exists for a particular group. The number of hops that announcement travels is a locally configured number. The GMs listen on a well-known multicast address for GC/KSes that provide service for groups they're interested in 👀 If more than one GC/KS is found, the GM picks the closest one (in terms of multicast hops). Then the GM sends a GSAKMP Request to Join message (RTJ) to the announced GC/KS. If the announcement turns out to be spurious, that gets reported to the appropriate management authorities 🚨 The ERA concept is slightly different from SAP, because it can happen over the data channel multicast address instead of a special multicast address dedicated to the SAP service.
An expanding ring search runs in the reverse order of the ERA 🔄 This time the GM is the one announcing. The (S-)GC/KSes listen for requests for service, specifically the RTJ, and the (S-)GC/KS responds to the RTJ. If the GM gets more than one response, it either ignores them or sends NACKs, depending on local configuration.
Anycast is very similar to ERS 💫 It can also be used to connect to the security infrastructure. In this case, the GM sends the RTJ to a well-known service request address. The anycast service then routes the RTJ to an appropriate GC/KS. The anycast service would have security infrastructure and network connectivity knowledge to make that connection happen.
Registration points can distribute a lot of group-relevant data, including security infrastructure 🎀 Many group applications rely on well-known registration points to advertise that groups are available, and there's no reason GSAKMP couldn't use the same approach to advertise the existence and location of its security infrastructure. This is simple if the application being supported already supports registration. The GSAKMP infrastructure can always provide a registration site if this security infrastructure discovery hub is needed. Registering S-GC/KSes at that site could be an efficient way to let GMs register.
GSAKMP infrastructure discovery can use whatever mechanism suits a particular multicast application's requirements, including mechanisms this architecture hasn't discussed 🧚 However, GSAKMP infrastructure discovery is not standardized by this version of the GSAKMP specification.
4.4. Concept of Operation 💅
This concept of operation shows how the different roles in GSAKMP work together to set up a secure group. It focuses on a secure group that uses the distributed key dissemination services of the S-GC/KS 🦋
4.4.1. Assumptions 🧐
The most basic assumption is that there is one or more trustworthy PKIs for the group. That trusted PKI is used to create and verify security policy rules.
There is a GO that all GMs recognize as having group policy creation authority. All GMs must be securely pre-configured to know the GO public key.
All GMs have access to the GO PKI information, both the trusted anchor public keys and the certificate path validation rules.
There is sufficient connectivity between the GSAKMP entities:
- The registration SA requires that GM can connect to the GC/KS or S-GC/KS using either TCP or UDP.
- The Rekey SA requires that the data-layer multicast communication service be available. This can be multicast IP, overlay networks using TCP, or NAT tunnels.
- GSAKMP can support many different data-layer secure applications, each with unique connectivity requirements.
4.4.2. Creation of a Policy Token 📜
The GO creates and signs the policy token for a group. The policy token contains the rules for access control and authorizations for a particular group.
The PT consists of the following information:
- Identification: This allows an unambiguous identification of the PT and the group.
- Access Control Rules: These rules specify who can have access to the group keys.
- Authorization Rules: These rules specify who can be a S-GC/KS.
- Mechanisms: These rules specify the security mechanisms that will be used by the group. This is necessary to ensure there is no weak link in the group security profile. For example, for IPsec, this could include SPD/SAD configuration data.
- Source authentication of the PT to the GO: The PT is a CMS signed object, and this allows all GMs to verify the PT.
4.4.3. Creation of a Group 🎉
The PT is sent to a potential GC/KS. This can happen in several ways, and the method of transmittal is outside the scope of GSAKMP. The potential GC/KS verifies the GO signature on the PT to make sure it comes from a trusted GO. Next, the GC/KS verifies that it is authorized to become the GC/KS, based on the authorization rules in the PT. If the GC/KS trusts the PT, is authorized to be a GC/KS, and is locally configured to become a GC/KS for a given group and the GO, then it creates the keys needed to start the group. The GC/KS takes whatever action is necessary (if any) to advertise its ability to distribute keys for the group. Then it listens for RTJs 👂
The PT has a sequence number. Every time a PT is distributed to the group, the group members verify that the sequence number on the PT is increasing 🔢 The PT lifetime isn't limited to a particular time interval, other than by the lifetimes imposed by some of its attributes (for example, signature key lifetime). The current PT sequence number is downloaded to the GM in the "Key Download" message. Also, to avoid replay attacks, this sequence number is never reset to a lower value (i.e., rollover to zero) as long as the group identifier remains valid and in use. The GO MUST preserve this sequence number across re-boots 🔒
4.4.4. Discovery of GC/KS 🔍
Potential GMs will hear about the new group through some mechanism: announcement, Anycast, or registration look-up. The GM then sends an RTJ to the GC/KS 💌
4.4.5. GC/KS Registration Policy Enforcement 🚪
The GC/KS may or may not require cookies, depending on the DoS environment and the local configuration 🍪
Once the RTJ has been received, the GC/KS verifies that the GM is allowed to have access to the group keys. Then it verifies the signature on the RTJ to make sure it was sent by the claimed identity. If the checks succeed, the GC/KS readies a "Key Download" message for the GM. If not, the GC/KS can notify the GM of a non-security-relevant problem.
4.4.6. GM Registration Policy Enforcement ✅
When the "Key Download" message arrives, the GM verifies the signature on the message. Then the GM retrieves the PT from the "Key Download" message and verifies that the GO created and signed the PT. Once the PT is verified as valid, the GM verifies that the GC/KS is authorized to distribute keys for this group. Then the GM verifies that the mechanisms used in the group are available and acceptable for protecting the GM's data (assuming the GM is a data source). The GM then accepts membership in this group 🥳
Next, the GM checks whether it is allowed to be a S-GC/KS for this group. If the GM is allowed to be a S-GC/KS AND the local GM configuration allows the GM to act as a S-GC/KS for this group, then the GM changes its operating state to S-GC/KS. The GO needs to assign the authority to become a S-GC/KS in a manner that supports the overall group integrity and operations 💜
4.4.7. Autonomous Distributed GSAKMP Operations 🦋
okay so in autonomous mode, each S-GC/KS runs its own largely self-contained sub-group 🫧 The Primary-GC/KS hands that sub-group's membership management over to the S-GC/KS. Basically the S-GC/KS handles each Group Member's registration and de-registration locally, with zero interaction with the Primary-GC/KS. 💅 Every so often, the Primary-GC/KS multicasts a Rekey Event message, but it's addressed only to its one or more S-GC/KS. 🫶
After a S-GC/KS successfully processes a Rekey Event message from the Primary-GC/KS, it sends its own Rekey Event message out to its sub-group. That message contains a copy of the group's new GTPK and policy token ✨ The S-GC/KS encrypts its Rekey Event message's sub-group key management info using Logical Key Hierarchy or a comparable rekey protocol. The rekey protocol is what gives forward and backward secrecy, so only the authorized sub-group members can decrypt and get access to the new GTPK and policy token. 🔐 How often the Primary-GC/KS sends a Rekey Event message is a policy token parameter, so it's set by the policy token. 🍓
Now for the special case: if a S-GC/KS detects an expelled or compromised group member, there's a mechanism that triggers an immediate group rekey, so it doesn't have to wait for the group's rekey period to run out 🚨 More on that below.
Each S-GC/KS will be registered by the GC/KS as a management node. Its responsibilities are GTPK distribution, access control policy enforcement, LKH tree creation, and distribution of LKH key arrays 🧚 The S-GC/KS will be registered into the primary LKH tree as an endpoint, and each S-GC/KS will hold an entire LKH key array for the GC's LKH key tree.
To keep things clear, here's how a distributed GSAKMP group gets created, in chronological order. 📅
First, the Group Owner creates a policy token that authorizes a subset of the group's membership to take on the S-GC/KS role. The GO needs to make sure the S-GC/KS rules in the policy token are stringent enough to build trust in the S-GC/KSes 👑 Then that policy token gets handed off to the primary GC.
The GC creates the GTPK and the initial LKH key tree. Then it waits for a potential S-GC/KS to send a Request to Join (RTJ) message 👀
A potential S-GC/KS will eventually send an RTJ. The GC enforces the access control policy defined in the policy token. If that all checks out, the S-GC/KS accepts the S-GC/KS role and creates its own LKH key tree for its sub-group membership 🌸
The S-GC/KS can then offer registration services for the group. There are optional local management decisions that let it control the scope of group members it serves. These are truly local management issues that let an S-GC/KS's administrators restrict service to potential GMs. 🎀 These local controls don't affect the overall group security policy defined in the policy token, so they're not a big deal for the group as a whole.
A potential Group Member sends an RTJ to the S-GC/KS. The S-GC/KS enforces the entire access control policy defined in the PT. The GM receives an LKH key array that matches the S-GC/KS's LKH tree. The key tree generated by the S-GC/KS is independent of the key tree generated by the GC/KS, and they share no common keys 🦋
Now the GM has the keys it needs to receive group traffic and be subject to rekey from the S-GC/KS. For the sake of this discussion, let's say the GM is about to get expelled from the group 🙈
The S-GC/KS gets notified that the GM is to be expelled. (That notification mechanism is outside the scope of this protocol.)
When the S-GC/KS is notified that a GM holding a key array in its LKH tree is to be expelled, it does two things. First, it starts a de-registration exchange with the GC/KS, identifying the member to be expelled. (So the S-GC/KS is proxying a Group Member's de-registration, letting the GC/KS know that the Group Member has been expelled from the group.) Second, the S-GC/KS waits for a rekey action from the GC/KS. How fast the GC/KS does that rekey is a management decision at the GC/KS. Security is best served by quick expulsion of untrusted members 💀
When the GC/KS gets the de-registration notification from the S-GC/KS, it registers the member being expelled. Then it follows group procedure for starting a rekey action (outside the scope of this protocol). The GC/KS also communicates the expelled member's information to the GO (outside the scope of this protocol too). With that info, the GO creates a new PT for the group, with the expelled GM identity added to the excluded list in the group's access control rules. The GO hands this new PT to the GC/KS so it can be distributed with the Rekey Event Message 💜
The GC/KS sends out a rekey operation with a new PT. The S-GC/KS receives the rekey and processes it. At the same time, every other S-GC/KS receives the rekey and notes the excluded GM identity. Each S-GC/KS checks its local identities to make sure the excluded GM isn't a local member. If it is, then that S-GC/KS creates a rekey message. The S-GC/KSes must always create a rekey message, whether or not the expelled Group Member is a member of their subtrees ✨
Then the S-GC/KS creates a local rekey message and sends the wrapped Group TPK to all members of its local LKH tree, except the excluded member(s) 🫶
5. Group Life Cycle 🌈
okay so the management of a cryptographic group follows a life cycle with three phases: group definition, group establishment, and security-relevant group maintenance. Group definition is where you define the parameters needed to support a secure group, including its policy token. Group establishment is the process of granting access to new members. Security-relevant group maintenance messages cover rekey, policy changes, member deletions, and group destruction. Each of these life cycle phases gets its own section below 💖
The use and processing of the optional Vendor ID payload for all messages can be found in Section 7.10.
5.1. Group Definition 🎀
A cryptographic group is set up to support secure communications among a group of individuals. The activities needed to create a policy token for a cryptographic group include:
- Determine Access Policy: identify the entities that are authorized to receive the group key.
- Determine Authorization Policy: identify which entities are authorized to perform security-relevant actions, including key dissemination, policy creation, and initiation of security-management actions.
- Determine Mechanisms: define the algorithms and protocols GSAKMP uses to secure the group.
- Create Group Policy Token: format the policies and mechanisms into a policy token, and apply the GO signature.
5.2. Group Establishment 🧚
GSAKMP Group Establishment consists of three mandatory-to-implement messages: the Request to Join, the Key Download, and the Key Download Ack/Failure. The exchange may also include two OPTIONAL error messages: the Request to Join Error and the Lack_of_Ack messages. Operating with only the mandatory messages is called "Terse Mode," while including the error messaging is called "Verbose Mode." GSAKMP implementations MUST support Terse Mode and MAY support Verbose Mode. Group Establishment is discussed in Section 5.2.1 ✨
A group is set in Terse or Verbose Mode by a policy token parameter. All (S-)GC/KSes in a Verbose Mode group MUST support Verbose Mode. GSAKMP allows Verbose Mode groups to have GMs that do not support Verbose Mode. Candidate GMs that don't support Verbose Mode and receive a RTJ-Error or Lack-of-Ack message must handle these messages gracefully 🙈 Also, a GM won't know ahead of time whether it's interacting with the (S-)GC/KS in Verbose or Terse Mode until it receives the policy token.
For denial of service protection, a Cookie Exchange MAY precede the Group Establishment exchange. The Cookie Exchange is described in Section 5.2.2 🛡️
Regardless of mode, any error message sent between component members indicates the first error encountered while processing the message 💅
5.2.1. Standard Group Establishment 🎀
Okay so, once a potential Group Controller Key Server (GC/KS) gets a policy token out-of-band, it checks the token and makes sure it's actually eligible to do GC/KS stuff 🔍. If it passes, it's cleared to make any group keys it needs and start building the group 🔑✨
Here's the GSAKMP Ladder Diagram, Figure 1, which shows how a cryptographic group gets set up 🦋. The left side is what the GC/KS does, and the right side is what the GMs do. Each message in the diagram gets its own breakdown in Sections 5.2.1.1 through 5.2.1.5 💅
CONTROLLER Mandatory/ MESSAGE MEMBER
Optional
!<-M----------Request to Join-------------!
<Process> ! !
<RTJ> ! !
!--M----------Key Download--------------->!
! !<Process KeyDL>
!--O-------Request to Join Error--------->! or
! ! <Proc RTJ-Err>
!<-M----Key Download - Ack/Failure--------!
<Process >! !
<KeyDL-A/F>! !
!--O------Lack of Acknowledgement-------->!
! ! <Proc LOA>
!<=======SHARED KEYED GROUP SESSION======>!Figure 1: GSAKMP Ladder Diagram
So the Request to Join message is sent by a potential GM to the GC/KS to ask for a spot in the cryptographic group 🙋♀️ It carries key creation material, freshness data, an optional choice of mechanisms, and the GM's signature 🖊️
The Key Download message goes from the GC/KS to the GM as a reply to a Request to Join that got accepted 🎉 This one is signed by the GC/KS and holds the GM's identifier, freshness data, key creation material, encrypted keys, and the encrypted policy token. The policy token helps the group get created in an orderly way, and it MUST include the group's identification, group permissions, group join policy, group controller key server identity, group management information, and digital signature of the GO. That's how the GM can check whether the group's policy plays nicely with its own local policy 🧐
The Request to Join Error message goes from the GC/KS to the GM when a Request to Join gets turned down 🙅♀️ This one is not signed by the GC/KS, and there are two reasons for that 💀 1) At this point the GM has no idea who's allowed to act as a GC/KS, so a signature would be meaningless to it. 2) Signing replies to denied join requests would open the door to a denial of service problem. The message says what went wrong with a value from this list: Invalid-Payload-Type, Invalid-Version, Invalid-Group-ID, Invalid-Sequence-ID, Payload-Malformed, Invalid-ID-Information, Invalid-Certificate, Cert-Type-Unsupported, Invalid-Cert-Authority, Authentication-Failed, Certificate-Unavailable, Unauthorized-Request, Prohibited-by-Group-Policy, and Prohibited-by-Locally-Configured-Policy.
The Key Download Ack/Failure message tells the GC/KS whether the GM actually received the Key Download 📬 It's signed by the GM and contains freshness data and a status.
The Lack_of_Ack message goes from the GC/KS to the GM when the Key Download Ack/Failure is missing or invalid 😬 It's signed and holds freshness and status data, and it's basically a warning that the GM is about to get evicted from the group if it doesn't send a valid Key Download Ack/Failure. Eviction means the member gets kicked out of the group after the next Rekey Event. The policy token says when a group needs to rekey itself. Section 5.3.2.1 has more on eviction 🫶
For the message structure sections that follow, the details about payload format and processing live in Section 7. Every message is identified by its exchange type in the message header 🏷️ Nonces MUST be present in the messages unless the system has synchronization time available ⏰
5.2.1.1. Request to Join
The exchange type for Request to Join is eight (8) 🔢
Table 1 shows what makes up a Request to Join message 📋
Message Name : Request to Join (RTJ)
Dissection : {HDR-GrpID, Key Creation, Nonce_I, [VendorID],
: [Notif_Mechanism_Choices], [Notif_Cookie],
: [Notif_IPValue]} SigM, [Cert]
Payload Types : GSAKMP Header, Key Creation, [Nonce], [Vendor
ID], Signature, [Certificate], [Notifications]
SigM : Signature of Group Member
Cert : Necessary Certificates, zero or more
{}SigX : Indicates fields used in Signature
[] : Indicate an optional data itemTable 1: Request to Join (RTJ) Message Definition
Like Figure 1 shows, a potential GM MUST generate and send an RTJ message to ask for permission to join the group 🙋♀️ At the very least, the GM MUST be able to manually configure where the RTJ gets sent ⚙️ As the dissection says, this message MUST contain a Key Creation payload for KEK determination 🔐 A Nonce payload MUST be included for freshness, and the Nonce_I value MUST be saved in case it's needed later 🧠 The GC/KS will only use this nonce if the group's policy token says to use nonces instead of synchronization time. An OPTIONAL Notification payload of type Mechanism Choices MAY be included to say which mechanisms the GM wants to use. If that payload isn't there, the GC/KS picks the default mechanisms the policy token specifies for the Key Download 🤷♀️
Then the GC/KS either accepts or denies the request, based on its local configuration 💅 <Process RTJ> is the GC/KS side of things that decides whether the RTJ gets acted on. The following checks SHOULD be performed in the order they're listed 📝
In this procedure, the GC/KS MUST check that the message header is properly formed, and it MUST confirm the message is for this group by checking the GroupID value 🔎 If the header checks pass, the sender's identity gets pulled out of the Signature payload. That identity MUST be used for access control checks and to find the GM's credentials (like a certificate) for message verification, and it MUST also be used in the Key Download message 🪪 After that, the GC/KS verifies the signature on the message to make sure it's authentic. The GC/KS MUST use verified and trusted authentication material from a known root 🌳 If the signature checks out, the GC/KS confirms that all the required payloads are there and properly formatted, based on the mechanisms that were announced and/or requested. If everything passes, the GC/KS creates and sends the Key Download message as described in Section 5.2.1.2 🚀
If the GM hears nothing back on its RTJ before its locally configured timeout value runs out, the GM SHOULD resend the RTJ message up to three (3) times 🔁
NOTE: At any one time, a GC/KS MUST process no more than one (1) valid RTJ message from a given GM per group until its pending registration protocol exchange concludes. 🚫
If any error happens while the GC/KS is processing an RTJ message, and the GC/KS is running in Terse Mode, the registration session MUST be terminated, and all saved state information MUST be cleared 💥
The OPTIONAL Notification payload of type Cookie is covered in Section 5.2.2 🍪
The OPTIONAL Notification payload of type IPValue may be used for the GM to pass a specific IP value along to the GC/KS 🌐
5.2.1.2. Key Download
okay bestie, the exchange type for Key Download is nine (9) 💖
the components of a Key Download Message are in Table 2 🎀
Table 2: Key Download (KeyDL) Message Definition
Message Name : Key Download (KeyDL)
Dissection : {HDR-GrpID, Member ID, [Nonce_R, Nonce_C], Key
Creation, (Policy Token)*, (Key Download)*,
[VendorID]} SigC, [Cert]
Payload Types : GSAKMP Header, Identification, [Nonce], Key
Creation, Policy Token, Key Download, [Vendor
ID], Signature, [Certificate]
SigC : Signature of Group Controller Key Server
Cert : Necessary Certificates, zero or more
{}SigX : Indicates fields used in Signature
[] : Indicate an optional data item
(data)* : Indicates encrypted informationso when the GC/KS gets a properly formed and verified RTJ message, it creates and sends the KeyDL message ✨ as the dissection shows, this message MUST contain payloads to hold the GM identification, the Key Creation material, the encrypted policy token, the encrypted key information, and the signature information 🔥 if synchronized time is not available, the Nonce payloads MUST be included in the message for freshness 🕰️
if they're present, the nonce values sent MUST be the GC/KS's generated Nonce_R value and the combined Nonce_C value. that combined one gets made from the GC/KS's Nonce_R value plus the Nonce_I value the GM sent in the RTJ 🧚
if two-party key determination is used, the key creation material from the GM and/or the GC/KS gets used to generate the key. how that key gets made depends on the key exchange, as defined in Section 7.11, "Key Creation Payload" 🌸 the policy token and key material are encrypted in the generated key 🔐
the GM MUST be able to process the Key Download message 💅 <Process KeyDL> is the list of GM actions that decide how the Key Download message gets handled. the following checks SHOULD be performed in the order presented 📋
in this procedure, the GM checks that the message header is properly formed and confirms the message is for this group by checking the GroupID 🦋 if the header checks pass, the GM MUST confirm that the message was meant for itself by comparing the Member ID in the Identification payload to its own identity 🫶
after the identification is confirmed, the freshness values get checked 👀 if nonces are being used, the GM MUST use its saved Nonce_I value, pull out the received GC/KS Nonce_R value, compute the combined Nonce_C value, and compare it to the received Nonce_C value. if nonces aren't being used, the GM MUST check the timestamp in the Signature payload to figure out if the message is new ⏰
once freshness is confirmed, the signature MUST be verified to make sure it's authentic 🔍 the GM MUST use verified and trusted authentication material from a known root 🌳 if the message signature verifies, the key creation material gets pulled out of the Key Creation payload to generate the KEK 🗝️ that KEK then decrypts the policy token data. the signature on the policy token MUST be verified ✅ access control checks MUST be performed on both the GO and the GC/KS to confirm their authorities within this group 👑 after all of those checks pass, the KEK can be used to decrypt and process the key material from the Key Download payload 🎉 if everything works, the GM will create and send the Key Download - Ack/Failure message, as described in Section 5.2.1.4 💖
the Policy Token and Key Download Payloads are sent encrypted in the KEK, which is generated from the Key Creation Payload information using the mechanisms defined in the group announcement 🔒 this means the sensitive policy and key data for the group, plus any potential rekey data for this individual, can't be read by anyone except the intended recipient 🙈✨
If any error happens during KeyDL message processing, it doesn't matter whether the GM is in Terse or Verbose Mode 💀 the registration session MUST be terminated, the GM MUST send a Key Download - Ack/Failure message, and all saved state information MUST be cleared. in Terse Mode, the Notification Payload will be of type NACK to show the termination. in Verbose Mode, the Notification Payload will contain the type of error that happened 🚨
5.2.1.3. Request to Join Error
the exchange type for Request to Join Error is eleven (11) 🦋
the components of the Request to Join Error Message are in Table 3 🌈
Table 3: Request to Join Error (RTJ-Err) Message Definition
Message Name : Request to Join Error (RTJ-Err)
Dissection : {HDR-GrpID, [Nonce_I], Notification, [VendorID]}
Payload Types : GSAKMP Header, [Nonce] Notification, [Vendor ID]so when the GC/KS gets an unacceptable RTJ, it MAY send a Request to Join Error (RTJ-Err) message with an appropriate Notification payload 🙅♀️ the RTJ-Err message is NOT a signed message, and here's the tea: the GM doesn't know yet who a valid GC/KS is, and the GC/KS shouldn't have to sign stuff and burn its valuable resources 🍓 after sending an RTJ-Err, the GC/KS MUST terminate the session, and all saved state information MUST be cleared 🧹
when the GM gets an RTJ-Err message, it checks the following 🔎 the GroupID in the header has to belong to a group the GM sent an RTJ to, and if it's present, the Nonce_I has to match a Nonce_I sent in an RTJ to that group. if those checks pass, the GM MAY terminate the state linked to that GroupID and nonce 💜 the GM SHOULD be able to receive a valid KeyDownload message for that GroupID and nonce after getting an RTJ-Err, for a locally configured amount of time ⏳
5.2.1.4. Key Download - Ack/Failure
the exchange type for Key Download - Ack/Failure is four (4) 🎀
the components of the Key Download - Ack/Failure Message are in Table 4 🌸
Table 4: Key Download - Ack/Failure (KeyDL-A/F) Message Definition
Message Name : Key Download - Ack/Failure (KeyDL-A/F)
Dissection : {HDR-GrpID, [Nonce_C], Notif_Ack, [VendorID]}SigM
Payload Types : GSAKMP Header, [Nonce], Notification, [Vendor
ID], Signature
SigM : Signature of Group Member
{}SigX : Indicates fields used in Signatureso when the GM properly processes a KeyDL message, it creates and sends the KeyDL-A/F message 💌 as the dissection shows, this message MUST contain payloads to hold a Notification payload of type Acknowledgement (ACK) and the signature information ✍️ if synchronized time is not available, the Nonce payload MUST be present for freshness, and the nonce value sent MUST be the GM's generated Nonce_C value 🕰️ if the GM doesn't get a KeyDL message within a locally configured amount of time, it MAY send a new RTJ 🔁 and if the GM gets a valid LOA (see Section 5.2.1.5) message from the GC/KS before it receives a KeyDL message, it SHOULD send a KeyDL-A/F message of type NACK, followed by a new RTJ 🙃
the GC/KS MUST be able to process the KeyDL-A/F message 💪 <Process KeyDL-A/F> is the list of GC/KS actions that decide how the KeyDL-A/F message gets handled. the following checks SHOULD be performed in the order presented 📝
in this procedure, the GC/KS checks that the message header is properly formed and confirms the message is for this group by checking the GroupID 🧐 if the header checks pass, the GC/KS MUST check the message for freshness. if nonces are being used, the GC/KS MUST use its saved Nonce_C value and compare it for equality with the received Nonce_C value. if nonces aren't being used, the GC/KS MUST check the timestamp in the Signature payload to figure out if the message is new ⏱️ once freshness is confirmed, the signature MUST be verified to make sure it's authentic 🔐 the GC/KS MUST use verified and trusted authentication material from a known root 🌳 if the message signature verifies, the GC/KS processes the Notification payload 📬 if the notification type is ACK, then the registration has completed successfully, and both parties SHOULD remove the state information linked to this GM's registration 🥳✨
if the GC/KS doesn't receive a KeyDL-A/F message of proper form, or can't correctly process it, or the Notification payload type is any value except ACK, or no KeyDL-A/F message arrives within the locally configured timeout, the GC/KS MUST evict this GM from the group in the next policy-defined Rekey Event 🚪💀 the GC/KS MAY send the OPTIONAL Lack_of_Ack message if it's running in Verbose Mode, as defined in Section 5.2.1.5 🌟
5.2.1.5. Lack of Ack ✨
okay bestie, the exchange type for Lack of Ack is twelve (12) 💅 here's the whole message layout 👇
Table 5: Lack of Ack (LOA) Message Definition
Message Name : Lack of Ack (LOA)
Dissection : {HDR-GrpID, Member ID, [Nonce_R, Nonce_C],
Notification, [VendorID]} SigC, [Cert]
Payload Types : GSAKMP Header, Identification, [Nonce],
Notification, [Vendor ID], Signature,
[Certificate]
SigC : Signature of Group Controller Key Server
Cert : Necessary Certificates, zero or more
{}SigX : Indicates fields used in Signature
[] : Indicate an optional data itemso if the GC/KS's local timeout runs out before it gets a KeyDL-A/F back from the GM, the GC/KS MAY create and send an LOA message to the GM 📨 as the dissection shows, this message MUST contain payloads holding the GM identification, a Notification of the error, and signature info 🫶
if synchronized time isn't available, the Nonce payloads MUST be present for freshness 🕰️ and the nonce values sent MUST be the GC/KS's generated Nonce_R value plus the combined Nonce_C value. that combined one comes from the GC/KS's Nonce_R and the Nonce_I the GM sent in the RTJ. both of these were already generated back during the Key Download message phase, so nothing new to make here ✨
the GM MAY be able to process the LOA message depending on its local configuration 🧚 <Process LOA> is the bit that spells out what the GM does with the LOA, and the checks SHOULD be performed in the order listed, no skipping ✅
in this procedure, the GM MUST verify that the message header is properly formed and confirm that the message is for this group by checking the GroupID value 🔍 if the header passes, the GM MUST confirm the message was meant for it by comparing the Member ID in the Identification payload to its own identity. after that, it's time for the freshness check 💫 if nonces are being used, the GM MUST use its save Nonce_I value, pull out the received GC/KS Nonce_R value, compute the combined Nonce_C value, and compare that to the received Nonce_C value. if nonces aren't being used, the GM MUST check the timestamp in the Signature payload to see if the message is new ⏰ once freshness is confirmed, access control checks MUST be performed on the GC/KS to figure out its authority within this group 👑 then the signature MUST be verified to make sure it's authentic. the GM MUST use verified and trusted authentication material from a known root 🔐
if all the checks succeed, the GM SHOULD resend a KeyDL-A/F for that session 🔁
5.2.2. Cookies: Group Establishment with Denial of Service Protection 🍪
this section defines an OPTIONAL capability that MAY be implemented into GSAKMP when you're using IP-based groups 🌸 it borrows heavily from [IKEv2], because IKEv2 already worked through this problem and GSAKMP is basically copying the idea 💖 this section paraphrases parts of [IKEv2] and tweaks them for GSAKMP to explain what cookies are for.
so there's an optional Cookie mode for GSAKMP, built to help against DoS attacks 🛡️
the term "cookies" comes from Karn and Simpson [RFC2522] in Photuris, an early key management proposal for IPSec 🦋 the ISAKMP fixed message header has two eight-octet fields called "cookies". GSAKMP doesn't keep that cookie data in the header though. it gets moved into a Notification payload instead 🎀
an attack we expect against GSAKMP is state and CPU exhaustion 😭 the target GC/KS gets flooded with Request to Join requests from forged IP addresses. it gets way less effective if the GC/KS keeps its CPU use minimal and doesn't commit any state to the conversation until it knows the potential GM can actually receive packets at the address it claims to be sending from 🧠 so when it's in Cookie mode, the GC/KS SHOULD reject initial Request to Join messages unless they contain a Notification payload of type "cookie" 🙅♀️ instead, it SHOULD send a Cookie Download message in response to the RTJ, with a cookie inside a notify payload of type Cookie_Required. any potential GM that gets one of these MUST retry the Request to Join message, this time including the responder-GC/KS-supplied cookie in its notification payload of type Cookie, as defined by the optional Notification payload of the Request to Join Msg in Section 5.2.1.1 ✨ this initial exchange then looks like Figure 2, with the new Cookie Download message's components in Table 6. the exchange type for Cookie Download is ten (10) 🔟
CONTROLLER MESSAGE MEMBER
in Cookie Mode
!<--Request to Join without Cookie Info---!
<Gen Cookie>! !
<Response >! !
!----------Cookie Download--------------->!
! ! <Process CD>
!<----Request to Join with Cookie Info----!
<Process> ! !
<RTJ > ! !
!-------------Key Download--------------->!
! ! <Proc KeyDL>
!<-----Key Download - Ack/Failure--------!
<Process >! !
<KeyDL-A/F>! !
!<=======SHARED KEYED GROUP SESSION======>!
Figure 2: GSAKMP Ladder Diagram with Cookies
Table 6: Cookie Download Message Definition
Message Name : Cookie Download
Dissection : {HDR-GrpID, Notif_COOKIE_REQUIRED, [VendorID]}
Payload Types : GSAKMP Header, Notification, [Vendor ID]the first two messages don't touch any GM or GC/KS state except to pass the cookie along 🍓
a GSAKMP implementation SHOULD generate its GC/KS cookies in a way that doesn't need any saved state to recognize a valid cookie when the second Request to Join message shows up 🧚♀️ the exact algorithms and syntax used to make cookies don't affect interoperability, so they aren't specified here 🙈
here's an example of how an endpoint could use cookies for limited DoS protection 🫧 a good way to do it is to set the cookie to:
Cookie = <SecretVersionNumber> | Hash(Ni | IPi | <secret>)<secret> is a randomly generated secret known only to the responder GC/KS and changed every so often 🔑 Ni is the nonce value from the initiator potential GM, and IPi is the asserted IP address of the candidate GM. that address is either the IP header's source IP address or the IP address inside the optional Notification "IPvalue" payload, if one is there 🌐 <SecretVersionNumber> should be changed whenever <secret> gets regenerated. the cookie can be recomputed when the "Request to Join with Cookie Info" arrives and then compared to the cookie in the received message 🧩 if it matches, the responder GC/KS knows every value has been computed since the last change to <secret>, and that IPi MUST be the same as the source address it saw the first time 💅 folding Ni into the hash means an attacker who only sees the Cookie_Download message can't successfully forge a "Request to Join with Cookie Info" message 🛑 and this Ni value MUST be the same Ni value from the original "Request to Join" message, or the calculation won't work 🥲
if a new value for <secret> gets picked while connections are still being initialized, a "Request to Join with Cookie Info" might come back with a <SecretVersionNumber> that isn't the current one 🌀 in that case, the responder GC/KS MAY reject the message by sending another response with a new cookie, or it MAY keep the old <secret> around for a short time and accept cookies computed from either one. the responder GC/KS SHOULD NOT accept cookies forever after <secret> changes, since that would undo part of the DoS protection 🚫 and it SHOULD change the value of <secret> frequently, especially if it's under attack 🚨
there's also an alternative for cookie generation in a NAT environment: swap the IPi value for the IPValue that came in the Notification payload of the RTJ message 🏠 that situation is flagged by the presence of a Notification payload of type IPValue, and with that swap, you can use a calculation similar to the one above ✨
5.2.3. Group Establishment for Receive-Only Members 📻
this section describes an OPTIONAL capability that may be implemented in a structured system 🗂️ where the authorized (S-)GC/KS is known ahead of time through out-of-band means, and where synchronized time is available ⏳
here's the difference from Standard Group Establishment: in the Receive-Only system, the GMs and (S-)GC/KSes run in Terse Mode and only exchange one message, the Key Download 🎯 potential new GMs don't send an RTJ at all. (S-)GC/KSes don't expect Key Download - ACK/Failure messages, and they don't remove GMs for not receiving the message 🙌
the operation goes like this: when an authorized out-of-band event happens, the (S-)GC/KS builds and sends a Key Download message to the new member, with the Nonce payloads ABSENT 📦 the GM then verifies:
- the ID payload identifies that GM
- the timestamp in the message is fresh
- the message is signed by an authorized (S-)GC/KS
- the signature on the message verifies
when you're using a Diffie-Hellman Key Creation Type for receive-only members, a static-ephemeral model is assumed 🌙 the Key Creation payload in the Key Download message holds the (S-)GC/KS's public component, and the member's public component is assumed to be obtained through secure out-of-band means 🔒
5.3. Group Maintenance 🛠️
the Group Maintenance phase covers member joins and leaves, group rekey activities, policy updates, and group destruction 💜 these activities are laid out in the following sections.
5.3.1. Group Management 👑
5.3.1.1. Rekey Events 🔑✨
okay so a Rekey Event is literally any action that needs a brand new group key and/or rekey info, and that includes a compromise report or a key expiring 💀 it's giving "time for a fresh start" energy.
Once an event has been identified (as the group security policy token defines it), the GC/KS MUST create and send a signed message with the GTPK and rekey info to the group. no skipping this step 🙅♀️
Every GM who gets this message MUST verify the signature so they know it's legit 🫶 If the signature doesn't verify, the message MUST be discarded, no exceptions bestie. If it does verify, the GM finds the right rekey download packet and decrypts the info using the stored rekey key(s). And if a new Policy Token rides along with the message, it MUST be encrypted in the old GTPK 🔐 the way that the old key protects the new one, iconic.
The exchange type for Rekey Event is five (5). 🎀
The components of a Rekey Event message are shown in Table 7:
Table 7: Rekey Event Message Definition
Message Name : Rekey Event
Dissection : {HDR-GrpID, ([Policy Token])*, Rekey Array,
[VendorID]}SigC, [Cert]
Payload Types : GSAKMP Header, [Policy Token], Rekey Event,
[Vendor ID], Signature, [Certificate],
SigC : Signature of Group Controller Key Server
Cert : Necessary Certificates, zero or more
{}SigX : Indicates fields used in Signature
(data)* : Indicates encrypted information
[] : Indicate an optional data item5.3.1.2. Policy Updates 📜
new policy tokens get sent through the Rekey Event message, ngl so simple 💅 These updates can ride along with an existing rekey event, or they can show up in a message where the Rekey Event Type of the Rekey Event Payload is set to None(0) (see Section 7.5.1).
A policy token MUST NOT be processed if the Rekey Event message carrying it fails processing. Policy token processing is type dependent and is beyond the scope of this document, so that's a whole other story 🙈
5.3.1.3. Group Destruction 💥
group destruction also goes through the Rekey Event message 😭 For a group destruction one, the Sequence ID is set to 0xFFFFFFFF. Once a group component receives this authenticated Rekey Event message, it MUST terminate processing of anything tied to that group. the end of an era 🥀
5.3.2. Leaving a Group 👋
there are a few ways a member can leave a group: eviction, voluntary departure without notice, and voluntary departure with notice (de-registration). We're gonna go through each one in this section 🧚
5.3.2.1. Eviction 🚫
at some point in a group's life, it might be desirable to evict one or more members. From a key management point of view, that means revoking their access to the group's protected data by "disabling" their keys. This happens with a Rekey Event, which Section 5.3.1.1 explains in more detail. If you also want to block their future access, the members MUST be added to a denied access control list, and the policy token's authorization rules MUST be appropriately updated so they exclude the expelled GM(s). After receiving a new PT, GMs SHOULD evaluate how trustworthy any recent application data from the expelled GM(s) is 🧐 main character energy for the rest of the group.
5.3.2.2. Voluntary Departure without Notice 🌸
if a member wants to leave a group where being in it costs them nothing and carries no responsibility, then the member MAY just delete their local copies of the group keys and stop group activities. Easy peasy 🦋
5.3.2.3. De-Registration 📝
if being in the group does come with cost or responsibility for the departing member, then the member SHOULD de-register when they want to leave. De-registration is a three-message exchange between the GM and the member's GC/KS: the Request_to_Depart, Departure_Response, and the Departure_Ack. Compliant GSAKMP implementations for GMs SHOULD support the de-registration messages. Compliant GSAKMP implementations for GC/KSes MUST support the de-registration messages. no cap, the GC/KS side is non-negotiable 👑
5.3.2.3.1. Request to Depart 🙋♀️
The Exchange Type for a Request_to_Depart Message is thirteen (13). The components of a Request_to_Depart Message are shown in Table 8. 🎀
Any GM that wants to start de-registration MUST generate and send an RTD message to tell the GC/KS it wants out. As the RTD message dissection defines, this message MUST contain payloads holding the GC/KS identification and a Notification that the GM wants to leave the group 💌
When synchronization time isn't available to the system (as the Policy Token defines it), a Nonce payload MUST be included for freshness, and the Nonce_I value MUST be saved for later use. Then this message MUST be signed by the GM ✍️
Table 8: Request_to_Depart (RTD) Message Definition
Message Name : Request_to_Depart (RTD)
Dissection : {HDR-GrpID, GC/KS_ID, [Nonce_I], Notif_Leave_Group,
[VendorID]} SigM, [Cert]
Payload Types : GSAKMP Header, Identification, [Nonce],
Notification, [Vendor ID], Signature,
[Certificate]
SigM : Signature of Group Member
Cert : Necessary Certificates, zero or more
{}SigX : Indicates fields used in Signature
[] : Indicate an optional data itemWhen the GC/KS gets an RTD message, it MUST verify that the message header is properly formed and confirm the message is for this group by checking the GroupID value. If the header checks pass, the identifier in the Identification payload gets compared to the GC/KS's own identity, to confirm the GM meant to talk to this GC/KS, the one that registered this member into the group. Next, the sender's identity is pulled from the Signature payload. That identity MUST be used to confirm the GM is a member of the group this GC/KS serves. Then the GC/KS checks the Notification payload to confirm the GM is asking to leave the group, and verifies the signature so it knows the message is authentic. The GC/KS MUST use verified and trusted authentication material from a known root 🔒 If every check passes and the message is processed successfully, the GC/KS MUST form a Departure_Response message as defined in Section 5.3.2.3.2. 🎉
If processing the message fails, the de-registration session MUST be terminated, and all state tied to that session gets removed. If the GC/KS is in Terse Mode, no error message goes back to the GM. If the GC/KS is in Verbose Mode, it sends a Departure_Response Message with a Notification Payload of type Request_to_Depart_Error 🫠
5.3.2.3.2. Departure_Response 💌
The Exchange Type for a Departure_Response Message is fourteen (14). The components of a Departure_Response Message are shown in Table 9. ✨
After a properly formed and verified RTD message, the GC/KS MUST create and send the DR message. As the message dissection defines, this message MUST contain payloads holding the GM identification, a Notification accepting the departure, and signature info. If synchronization time isn't available, the Nonce payloads MUST be included in the message for freshness 🕰️
Table 9: Departure_Response (DR) Message Definition
Message Name : Departure_Response (DR)
Dissection : {HDR-GrpID, Member_ID, [Nonce_R, Nonce_C],
Notification, [VendorID]} SigC, [Cert]
Payload Types : GSAKMP Header, Identification, [Nonce],
Notification, [Vendor ID], Signature,
[Certificate]
SigC : Signature of Group Member
Cert : Necessary Certificates, zero or more
{}SigX : Indicates fields used in Signature
[] : Indicate an optional data itemIf they're present, the nonce values sent MUST be the GC/KS's generated Nonce_R value and the combined Nonce_C value. That combined value is made using the GC/KS's Nonce_R and the Nonce_I the GM sent in the RTD. This Nonce_C value MUST be saved against this departing GM's ID 🗂️
The GM MUST be able to process the Departure_Response message. The following checks SHOULD be performed in the order presented, bestie 📋
The GM MUST verify that the message header is properly formed and confirm the message is for this group by checking the GroupID value. If the header checks pass, the GM MUST confirm the message was meant for itself by comparing the Member ID in the Identification payload to its own identity. After identity is confirmed, the freshness values get checked. If nonces are in use, the GM MUST use its saved Nonce_I value, extract the received GC/KS Nonce_R value, compute the combined Nonce_C value, and check it for equality against the received Nonce_C value. If nonces aren't in use, the GM MUST check the timestamp in the signature payload to see if the message is new. Once freshness is confirmed, the GM checks that the signer of the DR message is its authorized GC/KS. Then the signature MUST be verified to make sure it's authentic. The GM MUST use verified and trusted authentication material from a known root 🛡️ If the signature verifies, the GM MUST verify that the Notification is of Type Departure_Accepted or Request_to_Depart_Error.
If processing succeeds and the Notification payload is of type Departure_Accepted, the member MUST form the Departure_ACK message as defined in Section 5.3.2.3.3. If processing succeeds and the Notification payload is of type Request_to_Depart_Error, the member MUST remove all state tied to the de-registration session. If the member still wants to De-Register from the group, the member MUST restart the de-registration process 🔄
If processing fails, the de-registration session MUST be terminated, and all state tied to that session gets removed. If the GM is in Terse Mode, a Departure_Ack Message with a Notification Payload of type NACK goes to the GC/KS. If the GM is in Verbose Mode, the GM sends a Departure_Ack Message with a Notification Payload of the matching failure type 💀
5.3.2.3.3. Departure_ACK 🦋
Okay bestie, the Departure_ACK is the final "yup, got it" in the departure handshake ✨ Its Exchange Type is fifteen (15) 💅 Here's the message definition, Table 10:
Table 10: Departure_ACK (DA) Message Definition
Message Name : Departure_ACK (DA)
Dissection : {HDR-GrpID, [Nonce_C], Notif_Ack, [VendorID]}SigM
Payload Types : GSAKMP Header, [Nonce], Notification, [Vendor
ID], Signature
SigM : Signature of Group Member
{}SigX : Indicates fields used in SignatureSo after a properly processed Departure_Response, the GM is up next 🫶 The GM MUST create and send the Departure_ACK message. As the dissection shows, this message MUST contain payloads to hold a Notification payload of type Acknowledgement (ACK) and signature information. If synchronization time is not available, the Nonce payload MUST be present for freshness, and the nonce value transmitted MUST be the GM's generated Nonce_C value.
Now the GC/KS gets to do the checks 🕵️♀️ Upon receipt of the Departure_ACK, the GC/KS MUST perform the following checks. These checks SHOULD be performed in the order presented.
In this procedure, the GC/KS MUST verify that the message header is properly formed and confirm that this message is for this group by checking the value of the GroupID. If the header checks pass, the GC/KS MUST check the message for freshness. If using nonces, the GC/KS MUST use its saved Nonce_C value and compare it to the received Nonce_C value. If not using nonces, the GC/KS MUST check the timestamp in the signature payload to determine if the message is new. After freshness is confirmed, the signature MUST be verified to ensure its authenticity. The GC/KS MUST use verified and trusted authentication material from a known root. If the message signature verifies, the GC/KS processes the Notification payload. If the notification type is of type ACK, this is considered a successful processing of this message.
If the processing of the message is successful, the GC/KS MUST remove the member from the group. This MAY involve initiating a Rekey Event for the group. ✨
If the processing of the message fails or if no Departure_Ack is received, the GC/KS MAY issue a LOA message. 💀
6. Security Suite 🔐
The Security Definition Suite 1 MUST be supported. Other security suite definitions MAY be defined in other Internet specifications.
6.1. Assumptions 🌸
All potential GMs will have enough information available to them to use the correct Security Suite to join the group. This can be accomplished by a well-known default suite, 'Security Suite 1', or by announcing/posting another suite.
6.2. Definition Suite 1 💜
GSAKMP implementations MUST support the following suite of algorithms and configurations. The following definition of Suite 1 borrows heavily from IKE's Oakley group 2 definition and Oakley itself.
The GSAKMP Suite 1 definition gives all the algorithm and cryptographic definitions required to process group establishment messages. It is important to note that GSAKMP does not negotiate these cryptographic mechanisms. This definition is set by the Group Owner via the Policy Token (passed during the GSAKMP exchange for member verification purposes).
The GSAKMP Suite 1 definition is:
Key download and Policy Token encryption algorithm definition:
Algorithm: AES
Mode: CBC
Key Length: 128 bits
Policy Token digital signature algorithm is:
DSS-ASN1-DER
Hash algorithm is:
SHA-1
Nonce Hash algorithm is:
SHA-1
The Key Creation definition is:
Algorithm type is Diffie Hellman
MODP group definition
g: 2
p: "FFFFFFFF FFFFFFFF C90FDAA2 2168C234 C4C6628B 80DC1CD1"
"29024E08 8A67CC74 020BBEA6 3B139B22 514A0879 8E3404DD"
"EF9519B3 CD3A431B 302B0A6D F25F1437 4FE1356D 6D51C245"
"E485B576 625E7EC6 F44C42E9 A637ED6B 0BFF5CB6 F406B7ED"
"EE386BFB 5A899FA5 AE9F2411 7C4B1FE6 49286651 ECE65381"
"FFFFFFFF FFFFFFFF"
NOTE: The p and g values come from IKE [RFC2409], Section 6.2,
"Second Oakley Group", and p is 1024 bits long.
The GSAKMP message digital signature algorithm is:
DSS-SHA1-ASN1-DER
The digital signature ID type is:
ID-DN-STRING7. GSAKMP Payload Structure 💖
A GSAKMP Message is composed of a GSAKMP Header (Section 7.1) followed by at least one GSAKMP Payload. All GSAKMP Payloads are composed of the Generic Payload Header (Section 7.2) followed by the specific payload data. The message is chained by a preceding payload defining its succeeding payload. Payloads are not required to be in the exact order shown in the message dissection in Section 5, provided that all required payloads are present. Unless it is explicitly stated in a dissection that multiple payloads of a single type may be present, no more than one payload of each type allowed by the message may appear. The final payload in a message will point to no succeeding payload.
All fields of type integer in the Header and Payload structure that are larger than one octet MUST be converted into Network Byte Order prior to data transmission.
Padding of fields MUST NOT be done as this leads to processing errors.
When a message contains a Vendor ID payload, the processing of the payloads of that message is modified as defined in Section 7.10.
7.1. GSAKMP Header 🎀
7.1.1. GSAKMP Header Structure ✨
The GSAKMP Header fields are shown in Figure 3 and defined as:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! GroupID Type ! GroupID Length! Group ID Value ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! Next Payload ! Version ! Exchange Type !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Sequence ID !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 3: GSAKMP Header Format
Group Identification Type (1 octet) - Table 11 presents the group identification types. This field is treated as an unsigned value.
Table 11: Group Identification Types
Grp ID Type Value Description
_____________________________________________________________________
Reserved 0
UTF-8 1 Format defined in Section 7.1.1.1.1.
Octet String 2 This type MUST be implemented.
Format defined in Section 7.1.1.1.2.
IPv4 3 Format defined in Section 7.1.1.1.3.
IPv6 4 Format defined in Section 7.1.1.1.4.
Reserved to IANA 5 - 192
Private Use 193 - 255Group Identification Length (1 octet) - Length of the Group Identification Value field in octets. This value MUST NOT be zero (0). This field is treated as an unsigned value.
Group Identification Value (variable length) - Indicates the name/title of the group. All GroupID types should provide unique naming across groups. GroupID types SHOULD provide this capability by including a random element generated by the creator (owner) of the group of at least eight (8) octets, providing extremely low probability of collision in group names. The GroupID value is static throughout the life of the group.
Next Payload (1 octet) - Indicates the type of the next payload in the message. The format for each payload is defined in the following sections. Table 12 presents the payload types. This field is treated as an unsigned value.
Table 12: Payload Types
Next_Payload_Type Value
___________________________________
None 0
Policy Token 1
Key Download Packet 2
Rekey Event 3
Identification 4
Reserved 5
Certificate 6
Reserved 7
Signature 8
Notification 9
Vendor ID 10
Key Creation 11
Nonce 12
Reserved to IANA 13 - 192
Private Use 193 - 255Version (1 octet) - Indicates the version of the GSAKMP protocol in use. The current value is one (1). This field is treated as an unsigned value.
Exchange Type (1 octet) - Indicates the type of exchange (also known as the message type). Table 13 presents the exchange type values. This field is treated as an unsigned value.
Table 13: Exchange Types
Exchange_Type Value
________________________________________
Reserved 0 - 3
Key Download Ack/Failure 4
Rekey Event 5
Reserved 6 - 7
Request to Join 8
Key Download 9
Cookie Download 10
Request to Join Error 11
Lack of Ack 12
Request to Depart 13
Departure Response 14
Departure Ack 15
Reserved to IANA 16 - 192
Private Use 193 - 255Sequence ID (4 octets) - The Sequence ID is used for replay protection of group management messages. If the message is not a group management message, this value MUST be set to zero (0). The first value used by a (S-)GC/KS MUST be one (1). For each distinct group management message that this (S-)GC/KS transmits, this value MUST be incremented by one (1). Receivers of this group management message MUST confirm that the value received is greater than the value of the sequence ID received with the last group management message from this (S-)GC/KS. Group Components (e.g., GMs, S-GC/KSes) MUST terminate processing upon receipt of an authenticated group management message containing a Sequence ID of 0xFFFFFFFF. This field is treated as an unsigned integer in network byte order.
Length (4 octets) - Length of total message (header + payloads) in octets. This field is treated as an unsigned integer in network byte order.
7.1.1.1. GroupID Structure 🧚
This section defines the formats for the defined GroupID types.
7.1.1.1.1. UTF-8 🫶
okay so the UTF-8 GroupID type has its own layout, shown in Figure 4 🎀
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Random Value ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! UTF-8 String ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 4: GroupID UTF-8 Format
- Random Value (16 octets): for the UTF-8 GroupID type, this is a string of exactly 16 hexadecimal digits, converted from its octet values in network-byte order 🔥. The leading zero hexadecimal digits and the trailing zero hexadecimal digits are always kept in the string, never truncated 💅.
- UTF-8 String (variable length): the human readable bit of the GroupID, encoded in UTF-8 🌈. Its length is the (GroupID Length - 16) for the Random Value field, and the minimum length is one (1) octet ✨.
7.1.1.1.2. Octet String 🍓
the Octet String type is shown in Figure 5 🦋
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Random Value ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Octet String ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 5: GroupID Octet String Format
- Random Value (8 octets): an 8-octet unsigned random value, in network byte order format 🎲.
- Octet String (variable length): this is the Octet String part of the GroupID 🧚. Its length is the (GroupID Length - 8) for the Random Value field, and the minimum length is one (1) octet 💜.
7.1.1.1.3. IPv4 Group Identifier 🌸
the IPv4 Group Identifier type is shown in Figure 6 🫧
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Random Value ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! IPv4 Value !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 6: GroupID IPv4 Format
- Random Value (8 octets): an 8-octet unsigned random value, in network byte order format 🎀.
- IPv4 Value (4 octets): the IPv4 value, in network byte order format. This value MAY contain the multicast address of the group 🌐.
7.1.1.1.4. IPv6 Group Identifier 🧸
the IPv6 Group Identifier type is shown in Figure 7 🔮
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Random Value ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! IPv6 Value ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 7: GroupID IPv6 Format
- Random Value (8 octets): an 8-octet unsigned random value, in network byte order format 💖.
- IPv6 Value (16 octets): the IPv6 value, in network byte order format. This value MAY contain the multicast address of the group ✨.
7.1.2. GSAKMP Header Processing 🕵️♀️
when you're processing the GSAKMP Header, these fields MUST be checked for correct values, no exceptions 🚨:
- Group ID Type: the Group ID Type value MUST be checked to be a valid group identification payload type, as defined by Table 11. If it's not valid, an error is logged. If you're in Verbose Mode, a message with the notification value
Payload-Malformedgets sent 💀. - GroupID: the GroupID of the received message MUST be checked against the valid GroupIDs of the Group Component. If there's no match, an error is logged. Also, if you're in Verbose Mode, a message with the notification value
Invalid-Group-IDgets sent 🙈. - Next Payload: the Next Payload value MUST be checked to be a valid payload type, as defined by Table 12. If it's not valid, an error is logged. If you're in Verbose Mode, a message with the notification value
Invalid-Payload-Typegets sent 🫠. - Version: the GSAKMP version number MUST be checked that its value is one (1). For other values, check the processing info further down 👀. The GSAKMP version number MUST also be checked that it's consistent with the group's policy, as specified in its Policy Token. If the version isn't supported or authorized, an error is logged. If you're in Verbose Mode, a message with the notification value
Invalid-Versiongets sent 💅. - Exchange Type: the Exchange Type MUST be checked to be a valid exchange type, as defined by Table 13, and it MUST be the type the GSAKMP state machine is expecting to receive 🎯. If the exchange type isn't valid, an error is logged. If you're in Verbose Mode, a message with the notification value
Invalid-Exchange-Typegets sent ⭐. - Sequence ID: the Sequence ID value MUST be checked for correctness. For negotiation messages, this value MUST be zero (0). For group management messages, this value MUST be greater than the last sequence ID received from this (S-)GC/KS 🔢. Receiving an incorrect Sequence ID on group management messages MUST NOT cause a reply message to be generated, so no replies there, bestie 🤐. Getting an incorrect Sequence ID on non-group management messages means an error is logged. If you're in Verbose Mode, a message with the notification value
Invalid-Sequence-IDgets sent 🥺.
The length fields in the GSAKMP Header (Group ID Length and Length) help you process the message. If any of those fields is wrong, an error is logged. If you're in Verbose Mode, a message with the notification value Payload-Malformed gets sent 📏.
okay so now the plan for interop 🦄: some ideas are coming up here about how a GSAKMP version one (v1) implementation can play nicely with future versions of the protocol 🌈.
A (S-)GC/KS running in a multi-versioned group, as defined by the Policy Token, has lots of options for how it deals with the GMs in that group when it sends a rekey message 🧁.
One possible solution is for the (S-)GC/KS to send out multiple rekey messages, one for each version level it supports. Then each GM only processes the message for the version it's running at 🎠.
the other approach, and this one is so iconic: all GM v1 implementations MUST support embedding a v1 message inside a version two (v2) message 💖. If a GM running at v1 receives a GSAKMP message with a version value greater than one (1), the GM will try to process the information right after the Group Header as a Group Header for v1 of the protocol. If that really is a v1 Group Header, the rest of this v1 message gets processed right where it is. After processing this embedded v1 message, the data following it should be the payload identified by the Next Payload field in the original header of the message, and the v1 member ignores it 🙈. But if the payload after the initial header isn't a v1 Group Header, the GM will gracefully handle the unrecognized message 🫶.
7.2. Generic Payload Header 🎀
7.2.1. Generic Payload Header Structure 🧚
every GSAKMP payload defined in the following sections starts with a generic header, shown in Figure 8. This header gives you the payload "chaining" capability and clearly marks where a payload begins and ends 🔗. The Generic Payload Header fields work like this 👑:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 8: Generic Payload Header
- Next Payload (1 octet): identifies the payload type of the next payload in the message 🎈. If the current payload is the last one in the message, this field is 0. This field gives you the "chaining" capability. Table 12 lists the payload types. This field is treated as an unsigned value 🔢.
- RESERVED (1 octet): unused, set to 0 🫧.
- Payload Length (2 octets): the length in octets of the current payload, including the generic payload header 📦. This field is treated as an unsigned integer in network byte order format 🌸.
7.2.2. Generic Payload Header Processing 💅
when you're processing the Generic Payload Header, these fields MUST be checked for correct values 🔍:
- Next Payload: the Next Payload value MUST be checked to be a valid payload type, as defined by Table 12. If the payload type isn't valid, an error is logged. If you're in Verbose Mode, a message with the notification value
Invalid-Payload-Typegets sent 😭. - RESERVED: this field MUST contain the value zero (0). If it isn't zero (0), an error is logged. If you're in Verbose Mode, a message with the notification value
Payload-Malformedgets sent 💀.
The length field in the Generic Payload Header helps process the rest of the payload. If this field is wrong, an error is logged. If you're in Verbose Mode, a message with the notification value Payload-Malformed gets sent 🧷.
7.3. Policy Token Payload 🌟
7.3.1. Policy Token Payload Structure 🎀
Okay so the Policy Token Payload is basically where the group's authenticatable info lives 🔐 It describes the security-relevant behaviors, the access control parameters, and the security mechanisms. Figure 9 shows the layout:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Policy Token Type ! Policy Token Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 9: Policy Token Payload Format
Here's the field rundown, no cap 💅
Next Payload(1 octet): this is the ID of the payload type for the next payload in the message. If the current payload is the last one, this field is 0. This is the "chaining" capability 🔗 Table 12 has the payload types. It's treated as an unsigned value.RESERVED(1 octet): unused, set to 0 🤍Payload Length(2 octets): the length in octets of the current payload, including the generic payload header. It's an unsigned integer in network byte order.Policy Token Type(2 octets): tells you which kind of Policy Token is being used. Table 14 has the list 👑 It's an unsigned integer in network byte order.
Table 14: Policy Token Types
Policy_Token_Type Value Definition/Defined In
____________________________________________________________________
Reserved 0
GSAKMP_ASN.1_PT_V1 1 All implementations of GSAKMP
MUST support this PT format.
Format specified in [RFC4534].
Reserved to IANA 2 - 49152
Private Use 49153 - 65535Policy Token Data(variable length): holds the Policy Token info 🧁 The values are token-specific, and thePolicy Token Typefield tells you what format they're in.
If this payload is encrypted, only the Policy Token Data field gets encrypted 🔒 Super specific, I love that for us.
The payload type for the Policy Token Payload is one (1) ✨
7.3.2. Policy Token Payload Processing 💖
When you're processing the Policy Token Payload, these fields MUST be checked for correct values, bestie 🫶
Next Payload,RESERVED,Payload Length: these get processed exactly as defined in Section 7.2.2, "Generic Payload Header Processing". No skipping!Policy Token Type: the value MUST be checked to be a valid policy token type as defined by Table 14. If it isn't valid, an error gets logged. If you're in Verbose Mode, an appropriate message with the notification valuePayload-Malformedgets sent 😭Policy Token Data: this data MUST be processed according to the Policy Token Type you got. The type is what defines the format of the data, so it's giving very "read the label first" energy 🏷️
7.4. Key Download Payload 🔑
Refer to the terminology section for the different terms about keys used in this section. Keys are a whole vibe, so definitely check it 🗝️
7.4.1. Key Download Payload Structure 🌸
The Key Download Payload carries group keys (like group keys, initial rekey keys, and so on) 🧚 These payloads can have several security attributes applied to them, depending on the group's security policy. Figure 10 shows the format.
Here's the big rule: the group's security policy says the key download payload MUST be encrypted with a key encryption key (KEK) 🔐 The encryption mechanism gets specified in the Policy Token. Also, group members MUST create the KEK using the key creation method identified in the Key Creation Payload. Very important, don't skip it 🚨
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Number of Items ! Key Download Data Items ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 10: Key Download Payload Format
The Key Download Payload fields work like this 🎀
Next Payload(1 octet): the ID of the payload type for the next payload in the message. If the current payload is the last one, this field is 0. This is the "chaining" capability, and Table 12 has the payload types. It's treated as an unsigned value.RESERVED(1 octet): unused, set to 0 🤍Payload Length(2 octets): the length in octets of the current payload, including the generic payload header. Unsigned integer, network byte order.Number of Items(2 octets): the total number of group traffic protection keys and Rekey Arrays being passed in this data block 🍓 Unsigned integer, network byte order.Key Download Data Items(variable length): holds the Key Download info. It's a sequence of Type/Length/Data, one for each of theNumber of Items. Each item's format is in Figure 11 💅
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! KDD Item Type ! Key Download Data Item Length! ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ Data for Key Download Data Item (Key Datum/Rekey Array) ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 11: Key Download Data Item Format
For each Key Download Data Item, here's the data format 👑
- Key Download Data (KDD) Item Type (1 octet): the ID for the type of data in this item. See Table 15 for the possible values. It's treated as an unsigned value.
- Key Download Data Item Length (2 octets): the length in octets of the Data for the Key Download Data Item that comes after this field. Unsigned integer, network byte order.
- Data for Key Download Data Item (variable length): holds Keys and related info 🗝️ The format depends on the value of the KDD Item Type field. For a KDD Item Type of GTPK, this field contains a Key Datum, as defined in Section 7.4.1.1. For a KDD Item Type of Rekey - LKH, this field contains a Rekey Array, as defined in Section 7.4.1.2.
Table 15: Key Download Data Item Types
Key Download Data Value Definition
Item Type
_________________________________________________________________
GTPK 0 This type MUST be implemented.
This type identifies that the
data contains group traffic
protection key information.
Rekey - LKH 1 Optional
Reserved to IANA 2 - 192
Private Use 193 - 255Quick heads-up 🚨 The encryption of this payload only covers the data after the Generic Payload header (that's the Number of Items and Key Download Data Items fields). The rest stays readable.
The payload type for the Key Download Packet is two (2) 🦋
7.4.1.1. Key Datum Structure ✨
okay so a Key Datum holds everything about one key 🔑 bestie, this is the whole key's glow-up file. Figure 12 is the layout:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Key Type ! Key ID ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! Key Handle ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! Key Creation Date ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! ! Key Expiration Date ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ Key Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 12: Key Datum FormatKey Type (2 octets) - this is the cryptographic algorithm the key data is for 🔐. The value comes from the Policy Token, and you check Table 16 for the possible values. It's treated as an unsigned value.
Table 16: Cryptographic Key Types
Cryptographic_Key_Types Value Description/Defined In
____________________________________________________________________
Reserved 0 - 2
3DES_CBC64_192 3 See [RFC2451].
Reserved 4 - 11
AES_CBC_128 12 This type MUST be
supported. See [IKEv2].
AES_CTR 13 See [IKEv2].
Reserved to IANA 14 - 49152
Private Use 49153 - 65535Key ID (4 octets) - the permanent ID for every version of the key 🦋. The Policy Token MAY define this value. It's treated as an octet string.
Key Handle (4 octets) - this one pinpoints one specific version (instance) of a key 🎯. It's also treated as an octet string.
Key Creation Date (15 octets) - when this key data was first generated 🌸. It's a UTF-8 timestamp in the format YYYYMMDDHHMMSSZ, where YYYY is the year (0000 - 9999), MM is the numerical value of the month (01 - 12), DD is the day of the month (01 - 31), HH is the hour of the day (00 - 23), MM is the minute within the hour (00 - 59), SS is the seconds within the minute (00 - 59), and the letter Z means Zulu time. This format is loosely based on [RFC3161].
Key Expiration Date (15 octets) - when the key stops being valid for use ⏳. Same format as above: a UTF-8 timestamp in YYYYMMDDHHMMSSZ form, where YYYY is the year (0000 - 9999), MM is the numerical value of the month (01 - 12), DD is the day of the month (01 - 31), HH is the hour of the day (00 - 23), MM is the minute within the hour (00 - 59), SS is the seconds within the minute (00 - 59), and the letter Z indicates Zulu time. This format is loosely based on [RFC3161].
Key Data (variable length) - the actual key material 🗝️. Its format depends on the Key Type algorithm.
NOTE: The combination of the Key ID and the Key Handle MUST be unique within the group 💅. That pair is how a key gets uniquely identified, so no duplicates allowed, periodt!
7.4.1.2. Rekey Array Structure 🎀
A Rekey Array holds the info for the set of KEKs tied to a Group Member 💜. Figure 13 is the format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Rekey Version#! Member ID ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! Number of KEK Keys ! ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ Key Datum(s) ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 13: Rekey Array Structure FormatRekey Version (1 octet) - the version of the Rekey protocol the data is formatted in ✨. For Key Download Data Item Type of Rekey - LKH, check Section A.2 for what this value means. It's treated as an unsigned value.
Member ID (4 octets) - the Member ID of the Rekey sequence inside this Rekey Array 🦋. It's treated as an octet string. For Key Download Data Item Type of Rekey - LKH, refer to Section A.2 for a description of this value.
Number of KEK Keys (2 octets) - how many distinct KEK keys are in this sequence 🔢. It's treated as an unsigned integer in network byte order format.
Key Datum(s) (variable length) - the sequence of KEKs in Key Datum format 🗂️. Each one follows section 7.4.1.1.
Key ID (for Key ID within the Rekey) - LKH space - refer to Section A.2 for a description of this value 🧚.
7.4.2. Key Download Payload Processing 💖
okay bestie, before you touch the data, the payload contents MUST be decrypted 🔓.
When you're processing the Key Download Payload, these fields MUST be checked for correct values 👑:
- Next Payload, RESERVED, Payload Length - these get handled exactly like Section 7.2.2, "Generic Payload Header Processing" says.
- KDD Item Type - every KDD Item Type field MUST be checked to be a valid Key Download Data Item type from Table 15. If it's not valid, log an error. If you're in Verbose Mode, send a message with the notification value
Payload-Malformed🙈. - Key Type - every Key Type field MUST be checked to be a valid encryption type from Table 16. If it's not valid, log an error. If you're in Verbose Mode, send a message with the notification value
Invalid-Key-Information💀. - Key Expiration Date - every Key Expiration Date field MUST be checked to confirm it's a future time value and not a past one ⏰. If it's not valid, log an error. If you're in Verbose Mode, send a message with the notification value
Invalid-Key-Information🫶.
The length and counter fields are what help you process the payload 🧮. If any field turns out to be wrong, log an error. If you're in Verbose Mode, send a message with the notification value Payload-Malformed 😭.
7.5. Rekey Event Payload 🌈
Refer to the terminology section for the different terms about keys used in this section 📖.
7.5.1. Rekey Event Payload Structure 🦋
The Rekey Event Payload MAY contain multiple keys encrypted in Wrapping KEKs 🎁. Figure 14 shows the format. If the data for a Rekey Event Payload is too big for one payload, the sequence can be split across multiple Rekey Event Payloads at a Rekey Event Data boundary ✂️.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! RekeyEvnt Type! Rekey Event Header ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ Rekey Event Data(s) ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 14: Rekey Event Payload FormatThe Rekey Event Payload fields work like this 🧩:
Next Payload (1 octet) - the payload type of the next payload in the message 💌. If the current payload is the last one, this field is 0. This field gives you the "chaining" capability. Table 12 has the payload types. It's treated as an unsigned value.
RESERVED (1 octet) - unused, set to 0 🤍.
Payload Length (2 octets) - the length in octets of the current payload, including the generic payload header 📏. It's treated as an unsigned integer in network byte order format.
Rekey Event Type (1 octet) - which type of Rekey Event is being used 🎯. Table 17 lists the types. It's treated as an unsigned value.
Rekey Event Header (variable length) - the header info for the Rekey Event 📜. Its format is defined in Section 7.5.1.1, "Rekey Event Header Structure".
Rekey Event Data(s) (variable length) - the rekey info for the Rekey Event 🔑. Its format is defined in Section 7.5.1.2, "Rekey Event Data Structure".
The Rekey Event payload type is three (3) 🏷️.
Table 17: Rekey Event Types
Rekey_Event_Type Value Definition/Defined In
_____________________________________________________________________
None 0 This type MUST be implemented.
In this case, the size of the Rekey
Event Data field will be zero bytes
long. The purpose of a Rekey Event
Payload with type None is when it is
necessary to send out a new token
with no rekey information. GSAKMP
rekey msg requires a Rekey Event
Payload, and in this instance it
would have rekey data of type None.
GSAKMP_LKH 1 The rekey data will be of
type LKH formatted according to
GSAKMP. The format for this field
is defined in Section 7.5.1.2.
Reserved to IANA 2 - 192
Private Use 193 - 2557.5.1.1. Rekey Event Header Structure ✨
okay so the Rekey Event Header is giving main character energy 💅 Here's the layout in Figure 15:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Group ID Value ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ Group ID Value !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Time/Date Stamp ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! RekeyEnt Type ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Algorithm Ver ! # of Rekey Event Data(s) !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 15: Rekey Event Header Format
Here's what each field does, bestie 🎀
- Group Identification Value (variable length) - Indicates the name/title of the group to be rekeyed. This is the same format, length, and value as the Group Identification Value in Section 7.1, "GSAKMP Header". 🌸
- Time/Date Stamp (15 octets) - This is the time value when the Rekey Event Data was generated. This field contains the timestamp in UTF-8 format
YYYYMMDDHHMMSSZ, whereYYYYis the year (0000 - 9999),MMis the numerical value of the month (01 - 12),DDis the day of the month (01 - 31),HHis the hour of the day (00 - 23),MMis the minute within the hour (00 - 59),SSis the seconds within the minute (00 - 59), and the letterZindicates that this is Zulu time. This format is loosely based on [RFC3161]. 🕰️✨ - Rekey Event Type (1 octet) - This is the Rekey algorithm being used for this group. The values for this field can be found in Table 17. This field is treated as an unsigned value. 🔑
- Algorithm Version (1 octet) - Indicates the version of the Rekey Type being used. For Rekey Event Type of
GSAKMP_LKH, refer to Section A.2 for a description of this value. This field is treated as an unsigned value. 🦋 - # of Rekey Event Data(s) (2 octets) - The number of Rekey Event Data(s) contained in the Rekey Data. This value is treated as an unsigned integer in network byte order. 💜
7.5.1.2. Rekey Event Data Structure 🧚
okay so this part is iconic 😭 As defined in the Rekey Event Header, # of Rekey Data(s) field, multiple pieces of information are sent in a Rekey Event Data. Each end user will be interested in only one Rekey Event Data among all of the information sent. Each Rekey Event Data will contain all the Key Packages that a user requires. For each Rekey Event Data, the data following the Wrapping fields is encrypted with the key identified in the Wrapping Header. Figure 16 shows the format of each Rekey Event Data.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Packet Length ! Wrapping KeyID ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! Wrapping Key Handle ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! # of Key Packages !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Key Packages(s) ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 16: Rekey Event Data Format
- Packet Length (2 octets) - Length in octets of the Rekey Event Data, which consists of the # of Key Packages and the Key Packages(s). This value is treated as an unsigned integer in network byte order. 📦
- Wrapping KeyID (4 octets) - This is the Key ID of the KEK that is being used for encryption/decryption of the new (rekeyed) keys. For Rekey Event Type of Rekey - LKH, refer to Section A.2 for a description of this value. 🔐
- Wrapping Key Handle (4 octets) - This is a Key Handle of the KEK that is being used for encryption/decryption of the new (rekeyed) keys. Refer to Section 7.4.1.1 for the values of this field. 🎀
- # of Key Packages (2 octets) - The number of key packages contained in this Rekey Event Data. This value is treated as an unsigned integer in network byte order. 🌈
- Key Package(s) (variable length) - The type/length/value format of a Key Datum. The format for this is defined in Section 7.5.1.2.1. 💖
7.5.1.2.1. Key Package Structure 💅
okay bestie, each Key Package holds all the info about the key, no cap 🫶 Figure 17 shows the format for a Key Package.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! KeyPkg Type ! Key Package Length ! Key Datum ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 17: Key Package Format
- Key Package Type (1 octet) - The type of key in this key package. Legal values for this field are defined in Table 15, Key Download Data Types. This field is treated as an unsigned value. 🍓
- Key Package Length (2 octets) - The length of the Key Datum. This field is treated as an unsigned integer in network byte order format. 🌸
- Key Datum (variable length) - The actual data of the key. The format for this field is defined in Section 7.4.1.1, "Key Datum Structure". 🔑✨
7.5.2. Rekey Event Payload Processing ✨
Okay so when you're processing a Rekey Event Payload, these fields MUST get checked for correct values 💅
Next Payload,RESERVED,Payload Length: these get handled exactly the way Section 7.2.2, "Generic Payload Header Processing" says 🎀- Rekey Event Type field within "Rekey Event" payload header: the Rekey Event Type MUST be checked to be a valid rekey event type as defined by Table 17. If it's not valid, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 🙈
- Group ID Value: the Group ID value of the Rekey Event Header received message MUST be checked against the GroupID of the Group Component. If no match is found, the payload is discarded, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 🌸
- Date/Time Stamp: the Date/Time Stamp value of the Rekey Event Header MAY be checked to see if the Rekey Event generation time is recent relative to network delay and processing times. If the TimeStamp is judged not to be recent, an error gets logged. No response error message is generated for receipt of a Group Management Message ⏰
- Rekey Event Type field within the "Rekey Event Header": the Rekey Event Type of the Rekey Event Header received message MUST be checked to be a valid rekey event type, as defined by Table 17, and the same value of the Rekey Event Type earlier in this payload. If it's not valid or not equal to the previous value of the Rekey Event Type, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 🦋
- Algorithm Version: the Rekey Algorithm Version number MUST be checked to make sure the version indicated is supported. If it isn't, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 🧚
The length and counter fields are used to help process the message. If any field is found to be incorrect, then termination processing MUST be initiated 😭
A GM MUST process all the Rekey Event Datas, because based on the rekey method used there's a real chance that multiple Rekey Event Datas are for this GM. The Rekey Event Datas are processed in order until all of them are consumed 🍓
- Wrapping KeyID: the Wrapping KeyID MUST be checked against the list of stored KEKs that this GM holds. If a match is found, then keep processing this Rekey Event Data. Otherwise, skip to the next Rekey Event Data 🔑
- Wrapping Handle: if a matching Wrapping KeyID was found, then the Wrapping Handle MUST be checked against the handle of the KEK that the KeyID matched. If the handles match, then the GM will process the Key Packages associated with this Rekey Event Data. Otherwise, skip to the next Rekey Event Data 👑
If a GM has found a matching Wrapping KeyID and Wrapping Handle, the GM decrypts the remaining data in this Rekey Event Data according to policy, using the KEK defined by the Wrapping KeyID and Handle. After decrypting the data, the GM extracts the # of Key Packages field to help process the subsequent Key Packages. The Key Packages are processed as follows 🌈
- Key Package Type: the Key Package Type MUST be checked to be a valid key package type as defined by Table 15. If it's not valid, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 💜
- Key Package Length: the Key Package Length is used to process the subsequent Key Datum information 📏
- Key Type: the Key Type MUST be checked to be a valid key type as defined by Table 16. If the Key Package Type is not valid (yes, the spec really says Key Package Type in this line, so we keep it exactly 🙈), then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 🎀
- Key ID: the Key ID MUST be checked against the set of Key IDs that this user maintains for this Key Type. If no match is found, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 🔍
- Key Handle: the Key Handle is extracted as is, and it becomes the new Key Handle for the Key currently associated with the Key Package's Key ID 🫶
- Key Creation Date: the Key Creation Date MUST be checked to make sure it is subsequent to the Key Creation Date for the currently held key. If this date is prior to the currently held key, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message 📅
- Key Expiration Date: the Key Expiration Date MUST be checked to make sure it is subsequent to the Key Creation Date just received and that the time rules conform with policy. If the expiration date isn't subsequent to the creation date, or it doesn't conform with policy, then regardless of mode (e.g., Terse or Verbose) an error gets logged. No response error message is generated for receipt of a Group Management Message ⌛
- Key Data: the Key Data is extracted based on the length information in the key package 💖
If there were no errors when processing the Key Package, the key represented by the KeyID will have all of its data updated based on the received information ✨
7.6. Identification Payload 🌸
7.6.1. Identification Payload Structure 🪪
The Identification Payload contains entity-specific data used to exchange identification information. This information is used to verify the identities of members. Figure 18 shows the format of the Identification Payload 👀
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! ID Classif ! ID Type ! Identification Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 18: Identification Payload FormatThe Identification Payload fields work like this:
Next Payload(1 octet): identifies the payload type of the next payload in the message. If the current payload is the last one in the message, this field is 0. This is the "chaining" capability, and Table 12 lists the payload types. This field is treated as an unsigned value 🔗RESERVED(1 octet): unused, set to 0 🤫Payload Length(2 octets): the length in octets of the current payload, including the generic payload header. This field is treated as an unsigned integer in network byte order format 📦- Identification (ID) Classification (1 octet): classifies who owns the Identification Data. Table 18 lists the possible values for this field. This field is treated as an unsigned value 🏷️
- Identification (ID) Type (1 octet): specifies the type of identification being used. Table 19 lists the possible values for this type. This field is treated as an unsigned value. All defined types are OPTIONAL unless otherwise stated 🆔
- Identification Data (variable length): contains identity information. The values for this field are group specific, and the format is specified by the ID Type field. The format for this field is stated alongside the type in Table 19 🧾
The payload type for the Identification Payload is four (4) 🎯
Table 18: Identification Classification
ID_Classification Value
_______________________________
Sender 0
Receiver 1
Third Party 2
Reserved to IANA 3 - 192
Private Use 193 - 255 Table 19: Identification Types
ID_Type Value PKIX Cert Description
Field Defined In
_____________________________________________________________________
Reserved 0
ID_IPV4_ADDR 1 SubjAltName See [IKEv2]
iPAddress Section 3.5.
ID_FQDN 2 SubjAltName See [IKEv2]
dNSName Section 3.5.
ID_RFC822_ADDR 3 SubjAltName See [IKEv2]
rfc822Name Section 3.5.
Reserved 4
ID_IPV6_ADDR 5 SubjAltName See [IKEv2]
iPAddress Section 3.5.
Reserved 6 - 8
ID_DER_ASN1_DN 9 Entire Subject, See [IKEv2]
bitwise Compare Section 3.5.
Reserved 10
ID_KEY_ID 11 N/A See [IKEv2]
Reserved 12 - 29 Section 3.5.
Unencoded Name 30 Subject The format for
(ID_U_NAME) this type is
defined in
Section 7.6.1.1.
ID_DN_STRING 31 Subject See [RFC4514].
This type MUST
be implemented.
Reserved to IANA 32 - 192
Private Use 193 - 2557.6.1.1. ID_U_NAME Structure 🎀
okay so the ID_U_NAME type (Unencoded Name) is laid out in Figure 19, and honestly it's giving bit-level drama 🧚
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Serial Number ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! DN Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 19: Unencoded Name (ID-U-NAME) Format 🦋
Here's the breakdown of each field:
- Serial Number (20 octets): the certificate serial number 🔢. It's treated as an unsigned integer in network byte order format.
- Length (4 octets): the length in octets of the DN Data field 📏. It's also an unsigned integer in network byte order format.
- DN Data (variable length): the actual UTF-8 DN value (Subject field) 💅. Field delimiters use the slash (/) character, so you'd get something like
"/C=US/ST=MD/L=Somewhere/O=ACME, Inc./OU=DIV1/CN=user1/Email=user1@acme.com"(without the surrounding quotes). Iconic 🌈
7.6.2. Identification Payload Processing ✨
bestie, when you're processing the Identification Payload, these fields MUST be checked for correct values 👑:
- Next Payload, RESERVED, Payload Length: these get processed exactly as defined in Section 7.2.2, "Generic Payload Header Processing" 🫶
- Identification Classification: the Identification Classification value MUST be checked to be a valid identification classification type as defined by Table 18. If it isn't valid, an error is logged. If you're in Verbose Mode, an appropriate message with the notification value Payload-Malformed will be sent 💀
- Identification Type: the Identification Type value MUST be checked to be a valid identification type as defined by Table 19. If it isn't valid, an error is logged. If you're in Verbose Mode, an appropriate message with the notification value Payload-Malformed will be sent 😭
- Identification Data: this Identification Data MUST be processed according to the identification type specified. The type defines the format of the data 🍓 If the identification data is being used to find a match and no match is found, an error is logged. If you're in Verbose Mode, an appropriate message with the notification value Invalid-ID-Information will be sent 🙈
7.6.2.1. ID_U_NAME Processing 💖
When you're processing the Identification Data of type ID_U_NAME, these fields MUST be checked for correct values:
- Serial Number: the serial number MUST be a greater than or equal to one (1) to be a valid serial number from a conforming CA [RFC3280]. If it isn't valid, an error is logged. If you're in Verbose Mode, an appropriate message with the notification value Payload-Malformed will be sent 🔥
- DN Data: the DN data is processed as a UTF-8 string 🎀
- The CA: the CA MUST be a valid trusted policy creation authority as defined by the Policy Token 🫧
These 2 pieces of information, Serial Number and DN Data, work together to be used for party identification. These values are also used to help identify the certificate when necessary. Main character energy for these two fields 👑
7.7. Certificate Payload 🌸
7.7.1. Certificate Payload Structure 🦋
okay so the Certificate Payload is how you transport certificates or other certificate-related information via GSAKMP, and it can show up in any GSAKMP message 💅 Certificate payloads SHOULD be included in an exchange whenever an appropriate directory service (e.g., LDAP [RFC4523]) isn't available to distribute certificates. You MAY send multiple certificate payloads so the certificate chains can be verified 🔗 Conversely, zero (0) certificate payloads may be sent, and the receiving GSAKMP MUST rely on some other mechanism to retrieve certificates for verification purposes 🫶 Figure 20 shows the format of the Certificate Payload:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Cert Type ! Certificate Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 20: Certificate Payload Format 🌈
The Certificate Payload fields work like this:
- Next Payload (1 octet): the identifier for the payload type of the next payload in the message 🔗 If the current payload is the last in the message, this field will be 0. This is the "chaining" capability. Table 12 identifies the payload types. It's treated as an unsigned value.
- RESERVED (1 octet): unused, set to 0 🫧
- Payload Length (2 octets): the length in octets of the current payload, including the generic payload header 📏 It's treated as an unsigned integer in network byte order format.
- Certificate Type (2 octets): indicates the type of certificate or certificate-related information in the Certificate Data field ✨ Table 20 presents the types of certificate payloads. It's treated as an unsigned integer in network byte order format.
- Certificate Data (variable length): the actual encoding of certificate data 🎀 The type is indicated by the Certificate Type/Encoding field.
The payload type for the Certificate Payload is six (6) 🍓
Table 20: Certificate Payload Types 💜
Certificate_Type Value Description/
Defined In
_____________________________________________________________________
None 0
Reserved 1 - 3
X.509v3 Certificate 4 This type MUST be
-- Signature implemented.
-- DER Encoding Contains a DER
encoded X.509
certificate.
Reserved 5 - 6
Certificate Revocation List 7 Contains a BER
(CRL) encoded X.509 CRL.
Reserved 8 - 9
X.509 Certificate 10 See [IKEv2], Sec 3.6.
-- Attribute
Raw RSA Key 11 See [IKEv2], Sec 3.6.
Hash and URL of X.509 12 See [IKEv2], Sec 3.6.
Certificate
Hash and URL of X.509 13 See [IKEv2], Sec 3.6.
bundle
Reserved to IANA 14 -- 49152
Private Use 49153 -- 655357.7.2. Certificate Payload Processing 💅
When you're processing the Certificate Payload, these fields MUST be checked for correct values:
- Next Payload, RESERVED, Payload Length: these get processed as defined in Section 7.2.2, "Generic Payload Header Processing" 🫶
- Certificate Type: the Certificate Type value MUST be checked to be a valid certificate type as defined by Table 20. If it isn't valid, an error is logged. If you're in Verbose Mode, an appropriate message with the notification value Cert-Type-Unsupported will be sent 🙈
- Certificate Data: this Certificate Data MUST be processed according to the certificate type specified. The type defines the format of the data 🍓 Receiving a certificate of the trusted policy creation authority in a Certificate payload causes the payload to be discarded. This received certificate MUST NOT be used to verify the message. The certificate of the trusted policy creation authority MUST be retrieved by other means 🔥
7.8. Signature Payload 🧚
7.8.1. Signature Payload Structure
okay so the Signature Payload is where the sender gets to show off their digital signature 💅 it's the data made by the digital signature function, and it covers everything from the GSAKMP Message Header through the Signature Payload, stopping right before the Signature Data Length. the layout is below 🎀
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Signature Type ! Sig ID Type ! ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ Signature Timestamp ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ! Signer ID Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Signer ID Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Signature Length ! Signature Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
~ ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 21: Signature Payload Format
here's what each field is all about 🧚
Next Payload(1 octet) - the payload type of the next payload in the message. if the current payload is the last one, this is 0. this is the "chaining" capability 🔗 Table 12 has the payload types. it's treated as an unsigned value.RESERVED(1 octet) - unused, and set to 0 🫶Payload Length(2 octets) - how many octets the current payload is, including the generic payload header. it's an unsigned integer in network byte order.Signature Type(2 octets) - tells you what kind of signature this is. Table 21 has the allowed ones 👑 it's an unsigned integer in network byte order.
Table 21: Signature Types
Signature Type Value Description/
Defined In
_____________________________________________________________________
DSS/SHA1 with ASN.1/DER encoding 0 This type MUST
(DSS-SHA1-ASN1-DER) be supported.
RSA1024-MD5 1 See [RFC3447].
ECDSA-P384-SHA3 2 See [FIPS186-2].
Reserved to IANA 3 - 41952
Private Use 41953 - 65536Signature ID Type(1 octet) - tells you the format of the Signature ID Data 🦋 these values match the Identification Payload identification types, which are in Table 19. it's an unsigned value.Signature Timestamp(15 octets) - the time when the digital signature was applied ⏰ it's a UTF-8 timestamp in the format YYYYMMDDHHMMSSZ, where YYYY is the year (0000 - 9999), MM is the month (01 - 12), DD is the day of the month (01 - 31), HH is the hour of the day (00 - 23), MM is the minute within the hour (00 - 59), SS is the seconds within the minute (00 - 59), and the letter Z means Zulu time. the format is loosely based on [RFC3161].Signer ID Length(2 octets) - how many octets long the Signer's ID is. it's an unsigned integer in network byte order.Signer ID Data(variable length) - data that identifies the Signer's ID (for example, a DN) 🌸 the format depends on the Signature ID Type field, and it's shown wherever that type is defined. the contents of this field MUST be checked against the Policy Token to figure out the Signer's authority and access within the group. no skipping this part, bestie!Signature Length(2 octets) - how many octets long the Signature Data is. it's an unsigned integer in network byte order.Signature Data(variable length) - the data that comes out of applying the digital signature function to the GSAKMP message and/or payload ✨
the payload type for the Signature Payload is eight (8) 💜
7.8.2. Signature Payload Processing
okay, when you're processing the Signature Payload, these fields MUST be checked for correct values 🔍
Next Payload,RESERVED,Payload Length- these get handled the way Section 7.2.2, "Generic Payload Header Processing" says 🎀Signature Type- the Signature Type value MUST be checked to make sure it's a valid signature type from Table 21. if it isn't, an error gets logged. if you're in Verbose Mode, you send a message with the notification value Payload-Malformed 🙈Signature ID Type- the Signature ID Type value MUST be checked to make sure it's a valid signature ID type from Table 19. if it isn't, an error gets logged. if you're in Verbose Mode, you send a message with the notification value Payload-Malformed 💀Signature Timestamp- this field MAY be checked to see whether the signing time is fresh enough given expected network delays. that kind of check makes sense for systems where archived sequences of events are wanted 🕰️
NOTE: how old a signature timestamp is allowed to be, compared to the local system clock, is a locally configured parameter. it can be tuned through its GSAKMP management interface 🛠️
Signature ID Data- this field is used to identify the sending party. this information MUST then be used to confirm that the correct party sent it 🫶 the field is also used to fetch the right public key from the certificate so the message can be verified.Signature Data- this value MUST be compared to the recomputed signature to verify the message 🔐 for info on checking the certificates that prove the signature is valid, look at [RFC3280]. the signature can only be computed to compare against the signature data after the certificate identified by the Signature ID Data has been verified. one error that can come up during signature verification is Authentication-Failed 😭 errors that can show up while processing certificates for signature verification are: Invalid-Certificate, Invalid-Cert-Authority, Cert-Type-Unsupported, and Certificate-Unavailable.
the length fields in the Signature Payload are what you use to process the rest of the payload 📏 if any field turns out to be wrong, then termination processing MUST be initiated 🚨
7.9. Notification Payload
7.9.1. Notification Payload Structure
ngl the Notification Payload is the messenger 🕊️ it can carry both GSAKMP and group-specific data, and it's how you pass informational stuff along to a GSAKMP peer, like error conditions. you can send more than one independent Notification payload in a single GSAKMP message, which is so iconic 🌈 here's the layout in Figure 22:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Notification Type ! Notification Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 22: Notification Payload Format
the Notification Payload fields go like this 🦋
Next Payload(1 octet) - the payload type of the next payload in the message. if the current payload is the last one, this is 0. this is the "chaining" capability 🔗 Table 12 has the payload types. it's an unsigned value.RESERVED(1 octet) - unused, set to 0 🫶Payload Length(2 octets) - how many octets the current payload is, including the generic payload header. it's an unsigned integer in network byte order.Notification Type(2 octets) - tells you what kind of notification message this is 📣 Table 22 has the Notify Payload Types. it's an unsigned integer in network byte order.Notification Data(variable length) - extra informational or error data sent alongside the Notify Payload Type. the values here depend on the Domain of Interpretation (DOI) 🍓
the payload type for the Notification Payload is nine (9) 💖
Table 22: Notification Types
Notification Type Value
__________________________________________________________
None 0
Invalid-Payload-Type 1
Reserved 2 - 3
Invalid-Version 4
Invalid-Group-ID 5
Invalid-Sequence-ID 6
Payload-Malformed 7
Invalid-Key-Information 8
Invalid-ID-Information 9
Reserved 10 - 11
Cert-Type-Unsupported 12
Invalid-Cert-Authority 13
Authentication-Failed 14
Reserved 15 - 16
Certificate-Unavailable 17
Reserved 18
Unauthorized-Request 19
Reserved 20 - 22
Acknowledgement 23
Reserved 24 - 25
Nack 26
Cookie-Required 27
Cookie 28
Mechanism Choices 29
Leave Group 30
Departure Accepted 31
Request to Depart Error 32
Invalid Exchange Type 33
IPv4 Value 34
IPv6 Value 35
Prohibited by Group Policy 36
Prohibited by Locally Configured Policy 37
Reserved to IANA 38 - 49152
Private Use 49153 -- 655357.9.1.1. Notification Data - Acknowledgement (ACK) Payload Type ✨
okay so the data part of a Notification payload of type ACK is doing one of two jobs 💅 it either confirms that the Key Download message was received correctly, or it carries other receipt info when that's needed and the message is signed 🫶 no cap, it's a small but very important little field 🎀
Figure 23 shows the format of the Notification Data - Acknowledge Payload Type:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Ack Type ! Acknowledgement Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 23: Notification Data - Acknowledge Payload Type Format
The Notification Data - Acknowledgement Payload Type data fields go like this:
Ack Type (1 octet) - This tells you what kind of acknowledgement it is 🦋 Table 23 has the list of Notify Acknowledgement Payload Types. This field is treated as an unsigned value.
Table 23: Acknowledgement Types
ACK_Type Value Definition
_____________________________________________________
Simple 0 Data portion null.
Reserved to IANA 1 - 192
Private Use 193 - 2557.9.1.2. Notification Data - Cookie_Required and Cookie Payload Type 🍓
okay this one is giving "hold the cookie, don't touch it" energy 🙈 The data portion of the Notification payload of types Cookie_Required and Cookie holds the Cookie value. The responder GC/KS computed that value and sent it to the GM. The GM takes whatever it received and copies it into the Notification payload's Notification Data field of type Cookie, which gets sent back to the GC/KS in the "Request to Join with Cookie Info" message. the cookie value MUST NOT be modified 🌈 no edits, no touching, periodt 💅
The format for this is already described in the discussion on cookies in Section 5.2.2. ✨
7.9.1.3. Notification Data - Mechanism Choices Payload Type 🧚
the data portion of the Notification payload of type Mechanism Choices is where the GM lists the mechanisms it wants to use for negotiating with the GC/KS 💜 the GM sends this info in an RTJ message. Figure 24 shows the format. Multiple type|length|data choices can be strung together inside one notification payload, so a user can send all the relevant info in a single Notification Payload 🫶 The payload's length is what controls how the Notification Data Mechanism Choices field gets parsed. it's giving efficiency 🔥
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Mech Type ! Mechanism Choice Data !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+..Figure 24: Notification Data - Mechanism Choices Payload Type Format
The Notification Data - Mechanism Choices Payload Type data fields are defined like so:
Mechanism Type (1 octet) - This is the type of mechanism. Table 24 lists the Notify Mechanism Choices Mechanism Types. This field is treated as an unsigned value.
Table 24: Mechanism Types
Mechanism_Type Value Mechanism Choice
Data Value Table Reference
___________________________________________________________________
Key Creation Algorithm 0 Table 26
Encryption Algorithm 1 Table 16
Nonce Hash Algorithm 2 Table 25
Reserved to IANA 3 - 192
Private Use 193 - 255Mechanism Choice Data (2 octets) - This is the data value for whichever mechanism type got selected. The values depend on each Mechanism Type that's defined. All tables needed to define values that aren't defined elsewhere (in this specification or others) are defined right here 🦋 This field is treated as an unsigned integer in network byte order format.
Table 25: Nonce Hash Types
Nonce_Hash_Type Value Description
__________________________________________________________________
Reserved 0
SHA-1 1 This type MUST be supported.
Reserved to IANA 2 - 49152
Private Use 49153 - 655357.9.1.4. Notification Data - IPv4 and IPv6 Value Payload Types 🌸
the data portion of the Notification payload of type IPv4 and IPv6 value holds the right IP value in network byte order 💖 The creator of the message is the one who sets this value, so the receiver can use it.
7.9.2. Notification Payload Processing 💅
when you're processing the Notification Payload, these fields MUST be checked for correct values, no skipping 👑
- Next Payload, RESERVED, Payload Length - These fields are processed as defined in Section 7.2.2, "Generic Payload Header Processing".
- Notification Type - The Notification type value MUST be checked to be a notification type as defined by Table 22. If the value isn't valid, an error gets logged. If you're in Verbose Mode, a message with the notification value Payload-Malformed will be sent 😭
- Notification Data - This Notification Data MUST be processed according to the notification type specified. The type defines the format of the data. When processing this data, any type field MUST be checked against the appropriate table for correct values. If the contents of the Notification Data aren't valid, an error gets logged. If you're in Verbose Mode, a message with the notification value Payload-Malformed will be sent 💀
7.10. Vendor ID Payload 🦋
7.10.1. Vendor ID Payload Structure 🧚
the Vendor ID Payload carries a vendor-defined constant 🎀 Vendors use it to identify and recognize remote instances of their own implementations. It's basically how a vendor can try out new features while keeping backwards compatibility intact. Figure 25 shows the format.
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Vendor ID (VID) ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 25: Vendor ID Payload Format
A Vendor ID payload MAY announce that the sender can accept certain extensions to the protocol 🌈 or it MAY simply identify the implementation to help with debugging. A Vendor ID payload MUST NOT change the interpretation of any information defined in this specification. Multiple Vendor ID payloads MAY be sent. An implementation is NOT REQUIRED to send any Vendor ID payload at all, so no pressure 🫶
A Vendor ID payload may be sent as part of any message. Getting a familiar Vendor ID payload lets an implementation use the Private Use numbers described throughout this specification, meaning private payloads, private exchanges, private notifications, and so on 🍓 That also means all the processing rules for all the payloads now get modified so they recognize every value that Vendor ID defines, for all fields of all payloads. Unfamiliar Vendor IDs MUST be ignored 🙈
Writers of Internet-Drafts who want to extend this protocol MUST define a Vendor ID payload to announce that their Internet-Draft can implement the extension. It's expected that Internet-Drafts that gain acceptance and get standardized will be given assigned values from the Reserved to IANA range, and then the requirement to use a Vendor ID payload will go away 🦋
The Vendor ID payload fields are defined as follows:
Next Payload (1 octet) - Identifies the payload type of the next payload in the message. If the current payload is the last one in the message, this field will be 0. This field is what provides the "chaining" capability. Table 12 identifies the payload types. This field is treated as an unsigned value.
RESERVED (1 octet) - Unused, set to 0.
Payload Length (2 octets) - The length in octets of the current payload, including the generic payload header. This field is treated as an unsigned integer in network byte order format.
Vendor ID (variable length) - The Vendor ID value. The minimum length for this field is four (4) octets. Whoever picks the Vendor ID is responsible for making sure it's unique, even though there's no central registry for IDs 👑 Good practice is to include a company name, a person's name, or something similar. A message digest of a long unique string is preferable to the long unique string itself. 💜
The payload type for the Vendor ID Payload is ten (10).
7.10.2. Vendor ID Payload Processing 🌸
when you're processing the Vendor ID Payload, these fields MUST be checked for correct values 💅
- Next Payload, RESERVED, Payload Length - These fields are processed as defined in Section 7.2.2, "Generic Payload Header Processing".
- Vendor ID - The Vendor ID Data MUST be processed to figure out whether the implementation recognizes the Vendor ID value. If it isn't recognized, then no matter the mode (e.g., Terse or Verbose) this info gets logged. Processing of the message MUST continue regardless of whether this value is recognized ✨
It is recommended that implementations which want to use Vendor-ID-specific information try to process the Vendor ID payloads of an incoming message before doing the rest of the message processing 🧚 That way the implementation can notice that, when it handles the other payloads, it can use the bigger set of values for payload fields (Private Use values, etc.) defined by the recognized Vendor IDs. main character energy 👑
7.11. Key Creation Payload ✨
7.11.1. Key Creation Payload Structure 🔑
The Key Creation Payload carries the info used to make key encryption keys (KEKs) 🗝️. The security attributes for this payload live in the Policy Token 💅. Figure 26 shows what it looks like:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Key Creation Type ! Key Creation Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 26: Key Creation Payload Format ✨
Here's the breakdown of the Key Creation Payload fields 🎀:
- Next Payload (1 octet): the identifier for the payload type of the next payload in the message. If the current payload is the last in the message, this field will be 0. This is the "chaining" capability, and Table 12 lists the payload types. This field is treated as an unsigned value.
- RESERVED (1 octet): unused, set to 0 🤍.
- Payload Length (2 octets): the length in octets of the current payload, including the generic payload header. This field is treated as an unsigned integer in network byte order format.
- Key Creation Type (2 octets): the type of Key Creation being used. Table 26 lists the types of key creation information. This field is treated as an unsigned integer in network byte order format.
- Key Creation Data (variable length): the Key Creation information itself. The values here are group specific, and the format is set by the key creation type field 🧚.
The payload type for the Key Creation Packet is eleven (11) 💜.
Table 26: Types of Key Creation Information
Key Creation Type Value Definition/Defined In
_____________________________________________________________________
Reserved 0 - 1
Diffie-Hellman 2 This type MUST be supported.
1024-bit MODP Group Defined in [IKEv2] B.2.
Truncated If the output of the process
is longer than needed for
the defined mechanism, use
the first X low order bits
and truncate the remainder.
Reserved 3 - 13
Diffie-Hellman 14 Defined in [RFC3526].
2048-bit MODP Group If the output of the process
Truncated is longer than needed for
the defined mechanism, use
the first X low order bits
and truncate the remainder.
Reserved to IANA 15 - 49152
Private Use 49153 - 655357.11.2. Key Creation Payload Processing 🛠️
The details of the Key Creation Payload are defined in Section 7.11 🌸.
When you're processing the Key Creation Payload, these fields MUST be checked for correct values 🔍:
- Next Payload, RESERVED, Payload Length: these fields are processed as defined in Section 7.2.2, "Generic Payload Header Processing".
- Key Creation Type: the Key Creation Type value MUST be checked to be a valid key creation type as defined by Table 26. If the value isn't valid, an error is logged. If in Verbose Mode, an appropriate message containing notification value Payload-Malformed will be sent 🚨.
- Key Creation Data: this Key Creation Data MUST be processed according to the key creation type specified, so the KEK can be generated to protect the information sent in the appropriate message. The type defines the format of the data 🔐.
Implementations that want to derive other keys from the initial Key Creation keying material (for example, DH Secret keying material) MUST define a Key Creation Type other than one of those shown in Table 26. The new Key Creation Type must specify that derivation's algorithm, for which the KEK MAY be one of the keys derived. 💀
7.12. Nonce Payload 🎀
7.12.1. Nonce Payload Structure ✨
The Nonce Payload holds random data that guarantees freshness during an exchange and protects against replay attacks 🦋. Figure 27 shows the format:
0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Next Payload ! RESERVED ! Payload Length !
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
! Nonce Type ! Nonce Data ~
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+Figure 27: Nonce Payload Format 🌈
The Nonce Payload fields work like this 💅:
- Next Payload (1 octet): the identifier for the payload type of the next payload in the message. If the current payload is the last in the message, this field will be 0. This is the "chaining" capability, and Table 12 lists the payload types. This field is treated as an unsigned value.
- RESERVED (1 octet): unused, set to 0 🤍.
- Payload Length (2 octets): the length in octets of the current payload, including the generic payload header. This field is treated as an unsigned integer in network byte order format.
- Nonce Type (1 octet): the type of nonce being used. Table 27 lists the types of nonces. This field is treated as an unsigned value.
Table 27: Nonce Types
Nonce_Type Value Definition
_____________________________________________________________________
None 0
Initiator (Nonce_I) 1
Responder (Nonce_R) 2
Combined (Nonce_C) 3 Hash (Append
(Initiator_Value,Responder_Value))
The hash type comes from the
Policy (e.g., Security Suite
Definition of Policy Token).
Reserved to IANA 4 - 192
Private Use 192 - 255- Nonce Data (variable length): the nonce information itself. The values here are group specific, and the format is set by the Nonce Type field. If no group-specific information is provided, the minimum length for this field is 4 bytes 🧁.
The payload type for the Nonce Payload is twelve (12) 💖.
7.12.2. Nonce Payload Processing 🔎
When you're processing the Nonce Payload, these fields MUST be checked for correct values 👀:
- Next Payload, RESERVED, Payload Length: these fields are processed as defined in Section 7.2.2, "Generic Payload Header Processing".
- Nonce Type: the Nonce Type value MUST be checked to be a valid nonce type as defined by Table 27. If the value isn't valid, an error is logged. If in Verbose Mode, an appropriate message containing notification value Payload-Malformed will be sent 🚨.
- Nonce Data: this is the nonce data, and it must be checked according to its content. The size of this field is defined in Section 7.12, "Nonce Payload". Refer to Section 5.2, "Group Establishment", for interpretation of this field 🫶.
8. GSAKMP State Diagram ✨
okay so this section is the state map 🗺️ Figure 28 shows every state this protocol can be in, Table 28 explains what each state means, and Table 29 lists the transitions that move things between states 🦋
!-----------------> ( )
! !-------------> ( Idle ) <------------------!
! ! ( ) !
! ! ! ! !
! ! ! ! !
! ! (1a) (1) !
! ! ! ! !
! ! ! ! !
! ! V V !
! !---(5a)--- (Wait for ) (Wait for ) ----(5)-----!
! (Group ) (GC/KS Event) <---
! (Membership) ^ ! \ \
! ! ! ! \ \
! ! ! ! \--(2)---\
! (2a) (4)(3)
! ! ! !
! ! ! !
! V ! V
!-------(4a)--- (Wait for ) (Wait for )
(Group ) (Response )
(Membership) (from Key )
/--> (Event ) (Download )
/ /
/ /
/--(3a)---/
Figure 28: GSAKMP State Diagram Table 28: GSAKMP States
______________________________________________________________________
Idle : GSAKMP Application waiting for input
______________________________________________________________________
Wait for GC/KS Event : GC/KS up and running, waiting for events
______________________________________________________________________
Wait for Response : GC/KS has sent Key Download,
from Key Download : waiting for response from GM
______________________________________________________________________
Wait for Group : GM in process of joining group
Membership :
______________________________________________________________________
Wait for Group : GM has group key, waiting for
Membership Event : group management messages.
______________________________________________________________________ Table 29: State Transition Events
____________________________________________________________________
Transition 1 : Create group command
______________:_____________________________________________________
:
Transition 2 : Receive bad RTJ
: Receive valid command to change group membership
: Send Compromise message x times
: Member Deregistration
______________:_____________________________________________________
:
Transition 3 : Receive valid RTJ
______________:_____________________________________________________
:
Transition 4 : Timeout
: Receive Ack
: Receive Nack
______________:_____________________________________________________
:
Transition 5 : Delete group command
______________:_____________________________________________________
:
Transition 1a : Join group command
______________:_____________________________________________________
:
Transition 2a : Send Ack
______________:_____________________________________________________
:
Transition 3a : Receipt of group management messages
______________:_____________________________________________________
:
Transition 4a : Delete group command
: Deregistration command
______________:_____________________________________________________
:
Transition 5a : Time out
: Msg failure
: errors
:
____________________________________________________________________9. IANA Considerations 🎀
9.1. IANA Port Number Assignment
IANA has handed GSAKMP port number 3761 over in both the UDP and TCP spaces 🔌 All implementations MUST use this port assignment in the appropriate manner.
9.2. Initial IANA Registry Contents
Okay so these registry entries have been created 📋
- GSAKMP Group Identification Types (Section 7.1.1)
- GSAKMP Payload Types (Section 7.1.1)
- GSAKMP Exchange Types (Section 7.1.1)
- GSAKMP Policy Token Types (Section 7.3.1)
- GSAKMP Key Download Data Item Types (Section 7.4.1)
- GSAKMP Cryptographic Key Types (Section 7.4.1.1)
- GSAKMP Rekey Event Types (Section 7.5.1)
- GSAKMP Identification Classification (Section 7.6.1)
- GSAKMP Identification Types (Section 7.6.1)
- GSAKMP Certificate Types (Section 7.7.1)
- GSAKMP Signature Types (Section 7.8.1)
- GSAKMP Notification Types (Section 7.9.1)
- GSAKMP Acknowledgement Types (Section 7.9.1.1)
- GSAKMP Mechanism Types (Section 7.9.1.3)
- GSAKMP Nonce Hash Types (Section 7.9.1.3)
- GSAKMP Key Creation Types (Section 7.11.1)
- GSAKMP Nonce Types (Section 7.12.1)
Changes and additions to the following registries are by IETF Standards Action 🔒
- GSAKMP Group Identification Types
- GSAKMP Payload Types
- GSAKMP Exchange Types
- GSAKMP Policy Token Types
- GSAKMP Key Download Data Item Types
- GSAKMP Rekey Event Types
- GSAKMP Identification Classification
- GSAKMP Notification Types
- GSAKMP Acknowledgement Types
- GSAKMP Mechanism Types
- GSAKMP Nonce Types
Changes and additions to the following registries are by Expert Review 🧐
- GSAKMP Cryptographic Key Types
- GSAKMP Identification Types
- GSAKMP Certificate Types
- GSAKMP Signature Types
- GSAKMP Nonce Hash Types
- GSAKMP Key Creation Types
10. Acknowledgements 🫶
This document is the team effort of loads of people 💜 If there were no limit on how many authors could be listed on an RFC, these folks would be in there, in alphabetical order: Haitham S. Cruickshank of University of Surrey, Sunil Iyengar of University Of Surrey, Gavin Kenny of LogicaCMG, Patrick McDaniel of AT&T Labs Research, and Angela Schuett of NSA.
Then there are the people who deserve a huge thank you for helping make this protocol so much better ✨ Eric Harder is an author of Tunneled-GSAKMP, and the concepts from that work show up in GSAKMP too. Rod Fleischer, also a Tunneled-GSAKMP author, and Peter Lough were both key in coding a prototype of the GSAKMP software, and they helped define lots of areas of the protocol that were vague at best 🙈 Andrew McFarland and Gregory Bergren gave critical analysis of early versions of the specification 🔥 Ran Canetti analyzed the security of the protocol and suggested denial of service fixes that led to optional "cookie protection" 🛡️
11. References 📚
The references are the stuff this spec leans on, split into normative (you need these) and informative (good to know) piles 💅
11.1. Normative References
[DH77] Diffie, W., and M. Hellman, "New Directions in
Cryptography", IEEE Transactions on Information Theory,
June 1977.
[FIPS186-2] NIST, "Digital Signature Standard", FIPS PUB 186-2,
National Institute of Standards and Technology, U.S.
Department of Commerce, January 2000.
[FIPS196] "Entity Authentication Using Public Key Cryptography,"
Federal Information Processing Standards Publication 196,
NIST, February 1997.
[IKEv2] Kaufman, C., "Internet Key Exchange (IKEv2) Protocol",
RFC 4306, December 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2409] Harkins, D. and D. Carrel, "The Internet Key Exchange
(IKE)", RFC 2409, November 1998.
[RFC2412] Orman, H., "The OAKLEY Key Determination Protocol", RFC
2412, November 1998.
[RFC2627] Wallner, D., Harder, E., and R. Agee, "Key Management for
Multicast: Issues and Architectures", RFC 2627, June
1999.
[RFC3280] Housley, R., Polk, W., Ford, W., and D. Solo, "Internet
X.509 Public Key Infrastructure Certificate and
Certificate Revocation List (CRL) Profile", RFC 3280,
April 2002.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC4514] Zeilenga, K., Ed., "Lightweight Directory Access Protocol
(LDAP): String Representation of Distinguished Names",
RFC 4514, June 2006.
[RFC4534] Colegrove, A. and H. Harney, "Group Security Policy Token
v1", RFC 4534, June 2006.11.2. Informative References
[BMS] Balenson, D., McGrew, D., and A. Sherman, "Key Management
for Large Dynamic Groups: One-Way Function Trees and
Amortized Initialization", Work in Progress, February
1999.
[HCM] H. Harney, A. Colegrove, P. McDaniel, "Principles of
Policy in Secure Groups", Proceedings of Network and
Distributed Systems Security 2001 Internet Society, San
Diego, CA, February 2001.
[HHMCD01] Hardjono, T., Harney, H., McDaniel, P., Colegrove, A.,
and P. Dinsmore, "Group Security Policy Token:
Definition and Payloads", Work in Progress, August 2003.
[RFC2093] Harney, H. and C. Muckenhirn, "Group Key Management
Protocol (GKMP) Specification", RFC 2093, July 1997.
[RFC2094] Harney, H. and C. Muckenhirn, "Group Key Management
Protocol (GKMP) Architecture", RFC 2094, July 1997.
[RFC2408] Maughan D., Schertler M., Schneider M., and Turner J.,
"Internet Security Association and Key Management
Protocol (ISAKMP)", RFC 2408, Proposed Standard, November
1998
[RFC2451] Pereira, R. and R. Adams, "The ESP CBC-Mode Cipher
Algorithms", RFC 2451, November 1998.
[RFC2522] Karn, P. and W. Simpson, "Photuris: Session-Key
Management Protocol", RFC 2522, March 1999.
[RFC4523] Zeilenga, K., "Lightweight Directory Access Protocol
(LDAP) Schema Definitions for X.509 Certificates", RFC
4523, June 2006.
[RFC2974] Handley, M., Perkins, C., and E. Whelan, "Session
Announcement Protocol", RFC 2974, October 2000.
[RFC3161] Adams, C., Cain, P., Pinkas, D., and R. Zuccherato,
"Internet X.509 Public Key Infrastructure Time-Stamp
Protocol (TSP)", RFC 3161, August 2001.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
A., Peterson, J., Sparks, R., Handley, M., and E.
Schooler, "SIP: Session Initiation Protocol", RFC 3261,
June 2002.
[RFC3447] Jonsson, J. and B. Kaliski, "Public-Key Cryptography
Standards (PKCS) #1: RSA Cryptography Specifications
Version 2.1", RFC 3447, February 2003.
[RFC3526] Kivinen, T. and M. Kojo, "More Modular Exponential (MODP)
Diffie-Hellman groups for Internet Key Exchange (IKE)",
RFC 3526, May 2003.
[RFC3740] Hardjono, T. and B. Weis, "The Multicast Group Security
Architecture", RFC 3740, March 2004.
[RFC4086] Eastlake, D., 3rd, Schiller, J., and S. Crocker,
"Randomness Requirements for Security", BCP 106, RFC
4086, June 2005.Appendix A. LKH Information 🧚
okay bestie, this appendix is the LKH deep dive ✨ it gives an overview of LKH, defines the values for the GSAKMP message fields that are LKH-specific, and walks through an example of a Rekey Event Message using the LKH scheme 💅
A.1. LKH Overview
so LKH is basically a tree 🌳 it handles key distribution for a group rekey by organizing everything into a tree structure with subgroup keys 🦋 in the tree in Figure 29, the members live on the leaf nodes, and the intermediate nodes are abstract key groups. every member holds a bunch of keys: the group traffic protection key (GTPK), a subgroup key for every node on its path up to the root, and their own personal key 🎀 for example, member #3 has the GTPK, Key A, Key D, and Key 3 (iykyk 😭)
root
/ \
/ \
A B
/ \ / \
/ \ / \
C D E F
/ \ / \ / \ / \
/ \ / \ / \ / \
1 2 3 4 5 6 7 8
Figure 29: LKH Treethis keying topology gives you a super fast rekey for everyone except a compromised member 🔥 if Member 3 gets compromised, the new GTPK (GTPK') has to go out under a key Member 3 doesn't have. new Keys A and D (Key A' and Key D') also need to be securely sent to the other members of those subtrees. wrapping GTPK' with Key B securely delivers it to Members 5, 6, 7, and 8. Key C can encrypt both GTPK' and Key A' for Members 1 and 2. Member 3's nearest neighbor, Member 4, can get GTPK', Key D', and Key A' encrypted under its personal key, Key 4. by the end, the group is rekeyed and Member 3 is fully out 💀
A.2. LKH and GSAKMP
when you use LKH with GSAKMP, these issues need attention 👑
- Rekey Version # - the Rekey Version # in the Rekey Array of the Key Download Payload MUST contain the value one (1).
- Algorithm Version - the Algorithm Version in the Rekey Event Payload MUST contain the value one (1).
- Degree of Tree - the LKH tree can be of any degree; it need not be binary.
- Node Identification - each node in the tree is treated as a KEK. A KEK is just a special key. As the rule stated for all keys in GSAKMP, the set of the KeyID and the KeyHandle MUST be unique. A suggestion on how to do this will be given in this section.
- Wrapping KeyID and Handle - this is the KeyID and Handle of the LKH node used to wrap/encrypt the data in a Rekey Event Data.
for the following discussion, refer to Figure 30 🧚♀️
Key:
o: a node in the LKH tree
N: this line contains the KeyID node number
L: this line contains the MemberID number for all leaves ONLY
LEVEL
----
root o
N: / 1 \
/ \
1 o o
N: / 2 \ / 3 \
/ \ / \
2 o o o o
N: /4\ /5\ /6\ /7\
/ \ / \ / \ / \
3 o o o o o o o o
N: 8 9 10 11 12 13 14 15
L: 1 2 3 4 5 6 7 8
Figure 30: GSAKMP LKH Treeto guarantee KeyID uniqueness, the Rekey Controller SHOULD build a virtual tree and label the KeyID of each node, doing a breadth-first search of a fully populated tree regardless of whether or not the tree is actually full. for simplicity of this example, the root gets a KeyID value of one (1). these KeyID values stay static throughout the life of this tree.
the rekey arrays distributed to GMs also need a MemberID value to be distributed with the KeyDownload Payload. these MemberID values MUST be unique 🫶 so the set associated with each leaf node (the nodes from that leaf back to the root) gets a MemberID. in this example, the leftmost leaf node gets MemberID value of one (1). these 2 sets of values, the KeyIDs (represented on lines N) and the MemberIDs (represented on line L), give enough info in the KeyDownload and RekeyEvent Payloads to disseminate information. the KeyHandle associated with these keys is regenerated each time the key is replaced in the tree due to compromise.
A.3. LKH Examples
definition of values, bestie:
0xLLLL - length value
0xHHHHHHH# - handle value
YYYYMMDDHHMMSSZ - time valueA.3.1. LKH Key Download Example
this section gives an example of the data for the Key Download payload 📦 the GM gets MemberID 1 and its associated keys. the data shown comes after the Generic Payload Header.
| GTPK | MemberID 1 | KeyID 2 | KeyID 4 | KeyID 8
Number of Items - 0x0002
Item #1:
Key Download Data Item Type - 0x00 (GTPK)
Key Download Data Item Length - 0xLLLL
Key Type - 0x03 (3DES`CBC64`192)
Key ID - KEY1
Key Handle - 0xHHHHHHH0
Key Creation Date - YYYYMMDDHHMMSSZ
Key Expiration Date - YYYYMMDDHHMMSSZ
Key Data - variable, based on key definition
Item #2:
Key Download Data Item Type - 0x01 (Rekey - LKH)
Key Download Data Item Length - 0xLLLL
Rekey Version Number - 0x01
Member ID - 0x00000001
Number of KEK Keys - 0x0003
KEK #1:
Key Type - 0x03 (3DES`CBC64`192)
Key ID - 0x00000002
Key Handle - 0xHHHHHHH2
Key Creation Date - YYYYMMDDHHMMSSZ
Key Expiration Date - YYYYMMDDHHMMSSZ
Key Data - variable, based on key definition
KEK #2:
Key Type - 0x03 (3DES`CBC64`192)
Key ID - 0x00000004
Key Handle - 0xHHHHHHH4
Key Creation Date - YYYYMMDDHHMMSSZ
Key Expiration Date - YYYYMMDDHHMMSSZ
Key Data - variable, based on key definition
KEK #3:
Key Type - 0x03 (3DES`CBC64`192)
Key ID - 0x00000008
Key Handle - 0xHHHHHHH8
Key Creation Date - YYYYMMDDHHMMSSZ
Key Expiration Date - YYYYMMDDHHMMSSZ
Key Data - variable, based on key definitionA.3.2. LKH Rekey Event Example
this section gives an example of the data for the Rekey Event payload 💔 the GM with MemberID 6 gets keyed out of the group. the data shown comes after the Generic Payload Header.
| Rekey Event Type | GroupID | Date/Time | Rekey Type |
Algorithm Ver | # of Packets |
{ (GTPK)2, (GTPK, 3', 6')12, (GTPK, 3')7 }this data shows that three packets are being transmitted. read each packet like this:
- a) GTPK wrapped in LKH KeyID 2
- b) GTPK, LKH KeyIDs 3' & 6', all wrapped in LKH KeyID 12
- c) GTPK and LKH KeyID 3', all wrapped in LKH KeyID 7
NOTE: okay so in this example, multiple keys get encrypted under one key, but alternative pairings are totally legal too, like (GTPK)2, (GTPK)3', (3')6', (3')7', (6')12 🧩
we'll show the format for all the header data and packet (b) 🍓
Rekey Event Type - 0x01 (GSAKMP`LKH)
GroupID - 0xAABBCCDD
0x12345678
Time/Date Stamp - YYYYMMDDHHMMSSZ
Rekey Event Type - 0x01 (GSAKMP`LKH)
Algorithm Vers - 0x01
# of RkyEvt Pkts - 0x0003
For Packet (b):
Packet Length - 0xLLLL
Wrapping KeyID - 0x000C
Wrapping Key Handle - 0xHHHHHHHD
# of Key Packages - 0x0003
Key Package 1:
Key Pkg Type - 0x00 (GTPK)
Pack Length - 0xLLLL
Key Type - 0x03 (3DES`CBC64`192)
Key ID - KEY1
Key Handle - 0xHHHHHHH0
Key Creation Date - YYYYMMDDHHMMSSZ
Key Expiration Date - YYYYMMDDHHMMSSZ
Key Data - variable, based on key definition
Key Package 2:
Key Pkg Type - 0x01 (Rekey - LKH)
Pack Length - 0xLLLL
Key Type - 0x03 (3DES`CBC64`192)
Key ID - 0x00000003
Key Handle - 0xHHHHHHH3
Key Creation Date - YYYYMMDDHHMMSSZ
Key Expiration Date - YYYYMMDDHHMMSSZ
Key Data - variable, based on key definition
Key Package 3:
Key Pkg Type - 0x01 (Rekey - LKH)
Pack Length - 0xLLLL
Key Type - 0x03 (3DES`CBC64`192)
Key ID - 0x00000006
Key Handle - 0xHHHHHHH6
Key Creation Date - YYYYMMDDHHMMSSZ
Key Expiration Date - YYYYMMDDHHMMSSZ
Key Data - variable, based on key definitionAuthors' Addresses 🎀
Hugh Harney (point-of-contact)
SPARTA, Inc.
7110 Samuel Morse Drive
Columbia, MD 21046
Phone: (443) 430-8032
Fax: (443) 430-8181
EMail: hh@sparta.com
Uri Meth
SPARTA, Inc.
7110 Samuel Morse Drive
Columbia, MD 21046
Phone: (443) 430-8058
Fax: (443) 430-8207
EMail: umeth@sparta.com
Andrea Colegrove
SPARTA, Inc.
7110 Samuel Morse Drive
Columbia, MD 21046
Phone: (443) 430-8014
Fax: (443) 430-8163
EMail: acc@sparta.com
George Gross
IdentAware Security
82 Old Mountain Road
Lebanon, NJ 08833
Phone: (908) 268-1629
EMail: gmgross@identaware.comFull Copyright Statement 🌈
Copyright (C) The Internet Society (2006).
this document is subject to the rights, licenses and restrictions in BCP 78, and except as set forth there, the authors keep all their rights 💜
this document and the information in it are provided on an "AS IS" basis, and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE 🦋
Intellectual Property ✨
okay so the IETF is being very clear here 💅 it takes no position on whether any Intellectual Property Rights (or other rights) people claim over the tech in this doc are valid or in scope, and it doesn't say whether any license for them is actually available 🙈 it also doesn't claim it did any independent digging to find out what rights exist. if you want the procedures for rights in RFC docs, check out BCP 78 and BCP 79 📚
copies of IPR disclosures sent to the IETF Secretariat 📬, any assurances of licenses that are on offer, and the results of anyone trying to get a general license or permission to use those proprietary rights (for implementers or users of this spec) can all be found in the IETF online IPR repository at http://www.ietf.org/ipr 🔍
and the IETF is literally inviting anyone to speak up 🗣️ if you know about copyrights, patents, patent applications, or other proprietary rights that might cover tech needed to implement this standard, tell them! send it to ietf-ipr@ietf.org 💌 that's the bestie move 🫶
Acknowledgement
funding for the RFC Editor function comes from the IETF Administrative Support Activity (IASA) 💖 shoutout to them, honestly the unsung heroes ✨
📦 where this page comes from
- ietf: rfc4535 2006-06
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms