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

#include "include/jikev2sa.h"

Detailed Description

Internet Key Exchange (IKEv2) Security Association

(See RFC7296 for complete details)

IKE performs mutual authentication between two parties and establishes an IKE security association (SA) that includes shared secret information that can be used to efficiently establish SAs for Encapsulating Security Payload (ESP) [RFC4303] and/or Authentication Header (AH) [RFC4302] and a set of cryptographic algorithms to be used by the SAs to protect the traffic that they carry. In this document, the term "suite" or "cryptographic suite" refers to a complete set of algorithms used to protect an SA. An initiator proposes one or more suites by listing supported algorithms that can be combined into suites in a mix-and-match fashion. IKE can also negotiate use of IP Compression (IPComp) [IPCOMP] in connection with an ESP and/or AH SA. We call the IKE SA an "IKE_SA". The SAs for ESP and/or AH that get set up through that IKE_SA we call "CHILD_SAs"

All IKE communications consist of pairs of messages: a request and a response. The pair is called an "exchange". We call the first messages establishing an IKE_SA IKE_SA_INIT and IKE_AUTH exchanges and subsequent IKE exchanges CREATE_CHILD_SA or INFORMATIONAL exchanges. In the common case, there is a single IKE_SA_INIT exchange and a single IKE_AUTH exchange (a total of four messages) to establish the IKE_SA and the first CHILD_SA. In exceptional cases, there may be more than one of each of these exchanges. In all cases, all IKE_SA_INIT exchanges MUST complete before any other exchange type, then all IKE_AUTH exchanges MUST complete, and following that any number of CREATE_CHILD_SA and INFORMATIONAL exchanges may occur in any order. In some scenarios, only a single CHILD_SA is needed between the IPsec endpoints, and therefore there would be no additional exchanges. Subsequent exchanges MAY be used to establish additional CHILD_SAs between the same authenticated pair of endpoints and to perform housekeeping functions

IKE message flow always consists of a request followed by a response. It is the responsibility of the requester to ensure reliability. If the response is not received within a timeout interval, the requester needs to retransmit the request (or abandon the connection)

The first request/response of an IKE session (IKE_SA_INIT) negotiates security parameters for the IKE_SA, sends nonces, and sends Diffie-Hellman values. The second request/response (IKE_AUTH) transmits identities, proves knowledge of the secrets corresponding to the two identities, and sets up an SA for the first (and often only) AH and/or ESP CHILD_SA. The types of subsequent exchanges are CREATE_CHILD_SA (which creates a CHILD_SA) and INFORMATIONAL (which deletes an SA, reports error conditions, or does other housekeeping). Every request requires a response. An INFORMATIONAL request with no payloads (other than the empty Encrypted payload required by the syntax) is commonly used as a check for liveness. These subsequent exchanges cannot be used until the initial exchanges have completed

Scenarios

Security Gateway to Security Gateway Tunnel

Security Gateway to Security Gateway Tunnel

In this scenario, neither endpoint of the IP connection implements IPsec, but network nodes between them protect traffic for part of the way. Protection is transparent to the endpoints, and depends on ordinary routing to send packets through the tunnel endpoints for processing. Each endpoint would announce the set of addresses "behind" it, and packets would be sent in tunnel mode where the inner IP header would contain the IP addresses of the actual endpoints

Endpoint-to-Endpoint Transport

Endpoint to Endpoint

In this scenario, both endpoints of the IP connection implement IPsec, as required of hosts in[RFC4301]. Transport mode will commonly be used with no inner IP header. If there is an inner IP header, the inner addresses will be the same as the outer addresses. A single pair of addresses will be negotiated for packets to be protected by this SA. These endpoints MAY implement application layer access controls based on the IPsec authenticated identities of the participants. This scenario enables the end-to-end security that has been a guiding principle for the Internet since [RFC1958], [RFC2775], and a method of limiting the inherent problems with complexity in networks noted by [RFC3439]. Although this scenario may not be fully applicable to the IPv4 Internet, it has been deployed successfully in specific scenarios within intranets using IKEv1. It should be more broadly enabled during the transition to IPv6 and with the adoption of IKEv2

It is possible in this scenario that one or both of the protected endpoints will be behind a network address translation (NAT) node, in which case the tunneled packets will have to be UDP encapsulated so that port numbers in the UDP headers can be used to identify individual endpoints "behind" the NAT (see section 2.23)

Endpoint to Security Gateway Tunnel

Endpoint to Security Gateway Tunnel

In this scenario, a protected endpoint (typically a portable roaming computer) connects back to its corporate network through an IPsec-protected tunnel. It might use this tunnel only to access information on the corporate network, or it might tunnel all of its traffic back through the corporate network in order to take advantage of protection provided by a corporate firewall against Internet-based attacks. In either case, the protected endpoint will want an IP address associated with the security gateway so that packets returned to it will go to the security gateway and be tunneled back. This IP address may be static or may be dynamically allocated by the security gateway. In support of the latter case, IKEv2 includes a mechanism for the initiator to request an IP address owned by the security gateway for use for the duration of its SA. In this scenario, packets will use tunnel mode. On each packet from the protected endpoint, the outer IP header will contain the source IP address associated with its current location (i.e., the address that will get traffic routed to the endpoint directly), while the inner IP header will contain the source IP address assigned by the security gateway (i.e., the address that will get traffic routed to the security gateway for forwarding to the endpoint). The outer destination address will always be that of the security gateway, while the inner destination address will be the ultimate destination for the packet

Generating Keying Material

In the context of the IKE_SA, four cryptographic algorithms are negotiated: an encryption algorithm, an integrity protection algorithm, a Diffie-Hellman group, and a pseudo-random function (prf). The pseudo-random function is used for the construction of keying material for all of the cryptographic algorithms used in both the IKE_SA and the CHILD_SAs

We assume that each encryption algorithm and integrity protection algorithm uses a fixed-size key and that any randomly chosen value of that fixed size can serve as an appropriate key. For algorithms that accept a variable length key, a fixed key size MUST be specified as part of the cryptographic transform negotiated. For algorithms for which not all values are valid keys (such as DES or 3DES with key parity), the algorithm by which keys are derived from arbitrary values MUST be specified by the cryptographic transform. For integrity protection functions based on Hashed Message Authentication Code (HMAC), the fixed key size is the size of the output of the underlying hash function. When the prf function takes a variable length key, variable length data, and produces a fixed-length output (e.g., when using HMAC), the formulas in this document apply. When the key for the prf function has fixed length, the data provided as a key is truncated or padded with zeros as necessary unless exceptional processing is explained following the formula

Keying material will always be derived as the output of the negotiated prf algorithm. Since the amount of keying material needed may be greater than the size of the output of the prf algorithm, we will use the prf iteratively. We will use the terminology prf+ to describe the function that outputs a pseudo-random stream based on the inputs to a prf as follows: (where | indicates concatenation)

$ prf+ (K,S) = T1\;|\;T2\;|\;T3\;|\;T4\;|\;...$

where:

  • $ T1 = prf (K,\;S\;|\;0x01)$
  • $ T2 = prf (K,\;T1\;|\;S\;|\;0x01)$
  • $ T3 = prf (K,\;T2\;|\;S\;|\;0x01)$
  • $ T4 = prf (K,\;T3\;|\;S\;|\;0x01)$

continuing as needed to compute all required keys. The keys are taken from the output string without regard to boundaries (e.g., if the required keys are a 256-bit Advanced Encryption Standard (AES) key and a 160-bit HMAC key, and the prf function generates 160 bits, the AES key will come from T1 and the beginning of T2, while the HMAC key will come from the rest of T2 and the beginning of T3). The constant concatenated to the end of each string feeding the prf is a single octet. prf+ in this document is not defined beyond 255 times the size of the prf output

Generating Keying Material for CHILD_SAs

The shared keys are computed as follows. A quantity called $ SKEYSEED$ is calculated from the nonces exchanged during the IKE_SA_INIT exchange and the Diffie-Hellman shared secret established during that exchange. $ SKEYSEED$ is used to calculate seven other secrets:

  • $ SK_d$ - used for deriving new keys for the CHILD_SAs established with this IKE_SA
  • $SK_ai \; and \; SK_ar$ - used as a key to the integrity protection algorithm for authenticating the component messages of subsequent exchanges
  • $ SK_ei \; and \; SK_er$ - used for encrypting (and of course decrypting) all subsequent exchanges
  • $ SK_pi \; and \; SK_pr$ - which are used when generating an AUTH payload

$ SKEYSEED$ and its derivatives are computed as follows:

$ SKEYSEED = prf(Ni\;|\;Nr,\;g^ir)$

$ {SK_d\;|\;SK_ai\;|\;SK_ar\;|\;SK_ei\;|\;SK_er\;|\;SK_pi\;|\;SK_pr\;} = prf+ (SKEYSEED,\;Ni\;|\;Nr\;|\;SPIi\;|\;SPIr)$

(indicating that the quantities $ SK_d,\;SK_ai,\;SK_ar,\;SK_ei,\;SK_er,\;SK_pi,\;and\;SK_pr$ are taken in order from the generated bits of the prf+). g^ir is the shared secret from the ephemeral Diffie-Hellman exchange. g^ir is represented as a string of octets in big endian order padded with zeros if necessary to make it the length of the modulus. Ni and Nr are the nonces, stripped of any headers. If the negotiated prf takes a fixed-length key and the lengths of Ni and Nr do not add up to that length, half the bits must come from Ni and half from Nr, taking the first bits of each

The two directions of traffic flow use different keys. The keys used to protect messages from the original initiator are SK_ai and SK_ei. The keys used to protect messages in the other direction are SK_ar and SK_er. Each algorithm takes a fixed number of bits of keying material, which is specified as part of the algorithm. For integrity algorithms based on a keyed hash, the key size is always equal to the length of the output of the underlying hash function

A single CHILD_SA is created by the IKE_AUTH exchange, and additional CHILD_SAs can optionally be created in CREATE_CHILD_SA exchanges. Keying material for them is generated as follows:

$ KEYMAT = prf+(SK_d,\;Ni\;|\;Nr) $

Where Ni and Nr are the nonces from the IKE_SA_INIT exchange if this request is the first CHILD_SA created or the fresh Ni and Nr from the CREATE_CHILD_SA exchange if this is a subsequent creation.

For CREATE_CHILD_SA exchanges including an optional Diffie-Hellman exchange, the keying material is defined as:

$ KEYMAT = prf+(SK_d,\;g^ir\;(new) |\;Ni\;|\;Nr) $

where g^ir (new) is the shared secret from the ephemeral Diffie-Hellman exchange of this CREATE_CHILD_SA exchange (represented as an octet string in big endian order padded with zeros in the high-order bits if necessary to make it the length of the modulus). A single CHILD_SA negotiation may result in multiple security associations. ESP and AH SAs exist in pairs (one in each direction), and four SAs could be created in a single CHILD_SA negotiation if a combination of ESP and AH is being negotiated. Keying material MUST be taken from the expanded KEYMAT in the following order:

  • All keys for SAs carrying data from the initiator to the responder are taken before SAs going in the reverse direction
  • If multiple IPsec protocols are negotiated, keying material is taken in the order in which the protocol headers will appear in the encapsulated packet
  • If a single protocol has both encryption and authentication keys, the encryption key is taken from the first octets of KEYMAT and the authentication key is taken from the next octets

Each cryptographic algorithm takes a fixed number of bits of keying material specified as part of the algorithm

Header and Payload Formats

IKE Header

The format of the IKE header is shown in Figure 4

Figure 4: IKE Header Format [1]


  • Initiator’s SPI (8 octets) - A value chosen by the initiator to identify a unique IKE security association. This value MUST NOT be zero
  • Responder’s SPI (8 octets) - A value chosen by the responder to identify a unique IKE security association. This value MUST be zero in the first message of an IKE Initial Exchange (including repeats of that message including a cookie) and MUST NOT be zero in any other message
  • Next Payload (1 octet) - Indicates the type of payload that immediately follows the header. The format and value of each payload are defined below
  • Major Version (4 bits) - Indicates the major version of the IKE protocol in use. Implementations based on this version of IKE MUST set the Major Version to 2. Implementations based on previous versions of IKE and ISAKMP MUST set the Major Version to 1. Implementations based on this version of IKE MUST reject or ignore messages containing a version number greater than 2
  • Minor Version (4 bits) - Indicates the minor version of the IKE protocol in use. Implementations based on this version of IKE MUST set the Minor Version to 0. They MUST ignore the minor version number of received messages
  • Exchange Type (1 octet) - Indicates the type of exchange being used. This constrains the payloads sent in each message and orderings of messages in an exchange
IKE Exchange Type
Exchange TypeValue
RESERVED0-33
IKE_SA_INIT34
IKE_AUTH35
CREATE_CHILD_SA36
INFORMATIONAL37
RESERVED TO IANA38-239
Reserved for private use240-255
  • Flags (1 octet) - Indicates specific options that are set for the message. Presence of options are indicated by the appropriate bit in the flags field being set. The bits are defined LSB first, so bit 0 would be the least significant bit of the Flags octet. In the description below, a bit being ’set’ means its value is ’1’, while ’cleared’ means its value is ’0’
    • X(reserved) (bits 0-2) - These bits MUST be cleared when sending and MUST be ignored on receipt
    • I(nitiator) (bit 3 of Flags) - This bit MUST be set in messages sent by the original initiator of the IKE_SA and MUST be cleared in messages sent by the original responder. It is used by the recipient to determine which eight octets of the SPI were generated by the recipient
    • V(ersion) (bit 4 of Flags) - This bit indicates that the transmitter is capable of speaking a higher major version number of the protocol than the one indicated in the major version number field. Implementations of IKEv2 must clear this bit when sending and MUST ignore it in incoming messages
    • R(esponse) (bit 5 of Flags) - This bit indicates that this message is a response to a message containing the same message ID. This bit MUST be cleared in all request messages and MUST be set in all responses. An IKE endpoint MUST NOT generate a response to a message that is marked as being a response
    • X(reserved) (bits 6-7 of Flags) - These bits MUST be cleared when sending and MUST be ignored on receipt
  • Message ID (4 octets) - Message identifier used to control retransmission of lost packets and matching of requests and responses. It is essential to the security of the protocol because it is used to prevent message replay attacks
  • Length (4 octets) - Length of total message (header + payloads) in octets

Generic Payload Header

Generic Payload Header
  • Next Payload - Identifier for the payload type of the next payload in the message. If the current payload is the last in the message, then this field will be 0. This field provides a "chaining" capability whereby additional payloads can be added to a message by appending each one to the end of the message and setting the Next Payload field of the preceding payload to indicate the new payload’s type. An Encrypted payload, which must always be the last payload of a message, is an exception. It contains data structures in the format of additional payloads. In the header of an Encrypted payload, the Next Payload field is set to the payload type of the first contained payload (instead of 0); conversely, the Next Payload field of the last contained payload is set to zero. The payload type values are listed here. The values in the following table are only current as of the publication date of RFC 4306. Other values may have been added since then or will be added after the publication of this document. Readers should refer to IANA.org for the latest values
IKEv2 Payloads
Next Payload TypeNotationValue
No Next PayloadPYLD_NONE0
Security AssociationPYLD_SA33
Key ExchangePYLD_KE34
Identification - InitiatorPYLD_IDI35
Identification - ResponderPYLD_IDR36
CertificatePYLD_CERT37
Certificate RequestPYLD_CERTREQ38
AuthenticationPYLD_AUTH39
NoncePYLD_NINR40
NotifyPYLD_N41
DeletePYLD_D42
Vendor IDPYLD_V43
Traffic Selector InitiatorPYLD_TSI44
Traffic Selector ResponderPYLD_TSR45
Encrypted and AuthenticatedPYLD_SK46
ConfigurationPYLD_CP47
Extensible AuthenticationPYLD_EAP48
Generic Secure Password MethodPYLD_GSPM49
Group IdentificationPYLD_IDG50
Group Security AssociationPYLD_GSA51
Key DownloadPYLD_KD52
Encrypted and Authenticated FragmentPYLD_SKF53
Puzzle SolutionPYLD_PS54
  • Critical - MUST be set to zero if the sender wants the recipient to skip this payload if it does not understand the payload type code in the Next Payload field of the previous payload. MUST be set to one if the sender wants the recipient to reject this entire message if it does not understand the payload type. MUST be ignored by the recipient if the recipient understands the payload type code. MUST be set to zero for payload types defined in this document. Note that the critical bit applies to the current payload rather than the "next" payload whose type code appears in the first octet. The reasoning behind not setting the critical bit for payloads defined in this document is that all implementations MUST understand all payload types defined in this document and therefore must ignore the critical bit’s value. Skipped payloads are expected to have valid Next Payload and Payload Length fields. See Section 2.5 for more information on this bit
  • RESERVED - MUST be set to zero; MUST be ignored on receipt
  • Payload Length - Length in octets of the current payload, including the generic payload header

Security Association Payload

Security Association Payload
  • Proposals - One or more proposal substructures

Proposal Substructure

Proposal Substructure
  • Last Substruc - Specifies whether or not this is the last Proposal Substructure in the SA. This field has a value of 0 if this was the last Proposal Substructure, and a value of 2 if there are more Proposal Substructures. This syntax is inherited from ISAKMP, but is unnecessary because the last Proposal could be identified from the length of the SA. The value (2) corresponds to a payload type of Proposal in IKEv1, and the first four octets of the Proposal structure are designed to look somewhat like the header of a payload
  • RESERVED - MUST be sent as zero; MUST be ignored on receipt
  • Proposal Length - Length of this proposal, including all transforms and attributes that follow
  • Proposal Num - When a proposal is made, the first proposal in an SA payload MUST be 1, and subsequent proposals MUST be one more than the previous proposal (indicating an OR of the two proposals). When a proposal is accepted, the proposal number in the SA payload MUST match the number on the proposal sent that was accepted
  • Protocol ID - Specifies the IPsec protocol identifier for the current negotiation. The values in the following table are only current as of the publication date of RFC 4306. Other values may have been added since then or will be added after the publication of this document. Readers should refer to IANA.org for the latest values
IKEv2 Protocol IDs
ProtocolIdentifierProtocol ID
IKEPROTO_IKE1
AHPROTO_AH2
ESPPROTO_ESP3
FC_ESP_HDRPROTO_FC_ESP_HDR4
FC_CT_AUTHPROTO_FC_CT_AUTH5
  • SPI Size - For an initial IKE SA negotiation, this field MUST be zero; the SPI is obtained from the outer header. During subsequent negotiations, it is equal to the size, in octets, of the SPI of the corresponding protocol (8 for IKE, 4 for ESP and AH)
  • Num Transforms - Specifies the number of transforms in this proposal
  • SPI (variable) - The sending entity’s SPI. Even if the SPI Size is not a multiple of 4 octets, there is no padding applied to the payload. When the SPI Size field is zero, this field is not present in the Security Association payload
  • Transforms (variable) - One or more transform substructures

Transform Substructure

Transform Substructure
  • Last Substruc - Specifies whether or not this is the last Transform Substructure in the Proposal. This field has a value of 0 if this was the last Transform Substructure, and a value of 3 if there are more Transform Substructures. This syntax is inherited from ISAKMP, but is unnecessary because the last transform could be identified from the length of the proposal. The value (3) corresponds to a payload type of Transform in IKEv1, and the first four octets of the Transform structure are designed to look somewhat like the header of a payload
  • RESERVED - MUST be sent as zero; MUST be ignored on receipt
  • Transform Length - The length (in octets) of the Transform Substructure including Header and Attributes
  • Transform Type - The type of transform being specified in this transform. Different protocols support different Transform Types. For some protocols, some of the transforms may be optional. If a transform is optional and the initiator wishes to propose that the transform be omitted, no transform of the given type is included in the proposal. If the initiator wishes to make use of the transform optional to the responder, it includes a transform substructure with Transform ID = 0 as one of the options
  • Transform ID - The specific instance of the Transform Type being proposed see IANA.org for all values
IKEv2 Transform Types
DescriptionIdentifierTransform TypeUsed In
Encryption Algorithm (ENCR)IKE_ENCR1IKE and ESP
Pseudorandom Function (PRF)IKE_PRF2IKE
Integrity Algorithm (INTEG)IKE_INTEG3IKE, AH, optional in ESP
Diffie-Hellman Group (D-H)IKE_DH4IKE, optional in AH and ESP
Extended Sequence Numbers (ESN)IKE_ESN5AH and ESP

Transform Attributes

Transform Attributes
  • Attribute Format (AF) - Indicates whether the data attribute follows the Type/Length/Value (TLV) format or a shortened Type/Value (TV) format. If the AF bit is zero (0), then the attribute uses TLV format; if the AF bit is one (1), the TV format (with two-byte value) is used.
  • Attribute Type - Unique identifier for each type of attribute
  • Attribute Value (variable length) - Value of the attribute associated with the attribute type. If the AF bit is a zero (0), this field has a variable length defined by the Attribute Length field. If the AF bit is a one (1), the Attribute Value has a length of 2 octets

The only currently defined attribute type (Key Length) is fixed length; the variable-length encoding specification is included only for future extensions. Attributes described as fixed length MUST NOT be encoded using the variable-length encoding unless that length exceeds two bytes. Variable-length attributes MUST NOT be encoded as fixed-length even if their value can fit into two octets. Note: This is a change from IKEv1, where increased flexibility may have simplified the composer of messages but certainly complicated the parser

The Key Length attribute specifies the key length in bits (MUST use network byte order) for certain transforms as follows:

  • The Key Length attribute MUST NOT be used with transforms that use a fixed-length key. For example, this includes ENCR_DES, ENCR_IDEA, and all the Type 2 (Pseudorandom Function) and Type 3 (Integrity Algorithm) transforms specified in this document. It is recommended that future Type 2 or 3 transforms do not use this attribute
  • Some transforms specify that the Key Length attribute MUST be always included (omitting the attribute is not allowed, and proposals not containing it MUST be rejected). For example, this includes ENCR_AES_CBC and ENCR_AES_CTR
  • Some transforms allow variable-length keys, but also specify a default key length if the attribute is not included. For example, these transforms include ENCR_RC5 and ENCR_BLOWFISH

Key Exchange Payload

Key Exchange

A Key Exchange payload is constructed by copying one’s Diffie-Hellman public value into the "Key Exchange Data" portion of the payload. The length of the Diffie-Hellman public value for MODP groups MUST be equal to the length of the prime modulus over which the exponentiation was performed, prepending zero bits to the value if necessary

IKEv2 Diffie-Hellman Group Number
DescriptionIdentifierDiffie-Hellman Group Number
Diffie-Hellman MODP Group 768-bitDH_MODP_7681
Diffie-Hellman MODP Group 1024-bitDH_MODP_10242
Diffie-Hellman MODP Group 1536-bitDH_MODP_15365
Diffie-Hellman MODP Group 2048-bitDH_MODP_204814
Diffie-Hellman MODP Group 3072-bitDH_MODP_307215
Diffie-Hellman MODP Group 4096-bitDH_MODP_409616
Diffie-Hellman MODP Group 6144-bitDH_MODP_614417
Diffie-Hellman MODP Group 8192-bitDH_MODP_819218
Diffie-Hellman Elliptic Curve with 256-bit generatorDH_ECP_25619
Diffie-Hellman Elliptic Curve with 384-bit generatorDH_ECP_38420
Diffie-Hellman Elliptic Curve with 521-bit generatorDH_ECP_52121
Diffie-Hellman MODP Group 1024-bit with 160-bit SubgroupDH_MODP_1024_16022
Diffie-Hellman MODP Group 2048-bit with 224-bit SubgroupDH_MODP_2048_22423
Diffie-Hellman MODP Group 2048-bit with 256-bit SubgroupDH_MODP_2048_25624
Diffie-Hellman Elliptic Curve with 192-bit random curveDH_ECP_192_RANDOM25
Diffie-Hellman Elliptic Curve with 224-bit random curveDH_ECP_224_RANDOM26
Diffie-Hellman BrainPool Curve with 224-bit primeDH_BRAINPOOL_P224R127
Diffie-Hellman BrainPool Curve with 256-bit primeDH_BRAINPOOL_P256R128
Diffie-Hellman BrainPool Curve with 384-bit primeDH_BRAINPOOL_P384R129
Diffie-Hellman BrainPool Curve with 512-bit primeDH_BRAINPOOL_P512R130
Diffie-Hellman Elliptic Curve 25519DH_CURVE_2551931
Diffie-Hellman Elliptic Curve 448DH_CURVE_44832

Identification Payload

Identification Payload
  • ID Type - Specifies the type of Identification being used
  • RESERVED - MUST be sent as zero; MUST be ignored on receipt
  • Identification Data (variable length) - Value, as indicated by the Identification Type. The length of the Identification Data is computed from the size in the ID payload header
IKEv2 Identification Type
DescriptionIdentifierID Type
IPv4 Address ID typeID_IPV4_ADDR1
FQDN ID typeID_FQDN2
RFC822 Address IDID_RFC822_ADDR3
IPv6 Address ID typeID_IPV6_ADDR5
ASN1 DN IDID_DER_ASN1_DN9
ASN1 GN IDID_DER_ASN1_GN10
Key IDID_KEY_ID11
FC Name IDID_FC_NAME12
NULL IDID_NULL_ID13

Certification Payload

Certification Payload
  • Certificate Encoding - This field indicates the type of certificate or certificate-related information contained in the Certificate Data field. The values in the following table are only current as of the publication date of RFC 4306. Other values may have been added since then or will be added after the publication of this document. Readers should refer to IANA.org for the latest values
  • Certificate Data (variable length) - Actual encoding of certificate data. The type of certificate is indicated by the Certificate Encoding field
IKEv2 Certificate Encoding
DescriptionIdentifierCERT Encoding
Certificate encoded as X509_PKCS_7CERT_X509_PKCS_71
Certificate encoded as PGPCERT_PGP2
Certificate encoded as DNSCERT_DNS3
Certificate encoded as X509_SIGNATURECERT_X509_SIGNATURE4
Certificate encoded as KerberosCERT_KERBEROS6
Certificate encoded as CRLCERT_CRL7
Certificate encoded as ARLCERT_ARL8
Certificate encoded as SPKICERT_SPKI9
Certificate encoded as RAW_RSACERT_RAW_RSA10
Certificate encoded as X509 AttributeCERT_X509_ATTRIBUTE11
Certificate encoded as HASH URLCERT_HASH_URL12
Certificate encoded as HASH URL BundleCERT_HASH_URL_BUNDLE13
Certificate encoded as OSCP ContentCERT_OSCP_CONTENT14
Certificate encoded as RAW Public KeyCERT_RAW_PUBLIC_KEY15

Certification Request Payload

Certification Request Payload
  • Certificate Encoding - Contains an encoding of the type or format of certificate requested. Values are listed in Section 3.6
  • Certification Authority (variable length) - Contains an encoding of an acceptable certification authority for the type of certificate requested

Authentication Payload

Authentication Payload
  • Auth Method - Specifies the method of authentication used. The types of signatures are listed here. The values in the following table are only current as of the publication date of RFC 4306. Other values may have been added since then or will be added after the publication of this document. Readers should refer to IANA.org for the latest values
    • RSA Digital Signature - Computed as specified in Section 2.15 using an RSA private key with RSASSA-PKCS1-v1_5 signature scheme specified in [PKCS1] (implementers should note that IKEv1 used a different method for RSA signatures). To promote interoperability, implementations that support this type SHOULD support signatures that use SHA-1 as the hash function and SHOULD use SHA-1 as the default hash function when generating signatures. Implementations can use the certificates received from a given peer as a hint for selecting a mutually understood hash function for the AUTH payload signature. Note, however, that the hash algorithm used in the AUTH payload signature doesn’t have to be the same as any hash algorithm(s) used in the certificate(s)
    • Shared Key Message Integrity Code - Computed as specified in Section 2.15 using the shared key associated with the identity in the ID payload and the negotiated PRF
    • DSS Digital Signature - Computed as specified in Section 2.15 using a DSS private key (see [DSS]) over a SHA-1 hash
    • Elliptic Curve DSA (ECDSA) - Computed as specified in Section 2.15 encoding of the computed signature consisting of the concatenation of a pair of integers r and s. The definitions of r and s are given in Section 8 RFC4754
    • Digital Signature - Computer as specified in Section 2.15 with authentication method to support signature methods in a more general way. The current signature-based authentication methods in IKEv2 are per algorithm, i.e., there is one for RSA digital signatures, one for DSS digital signatures (using SHA-1), and three for different ECDSA curves, each tied to exactly one hash algorithm. This design is cumbersome when more signature algorithms, hash algorithms, and elliptic curves need to be supported:
      • In IKEv2, authentication using RSA digital signatures calls for padding based on RSASSA-PKCS1-v1_5, although the newer RSASSA-PSS padding method is now recommended. (See Section 5 of "Additional Algorithms and Identifiers for RSA Cryptography for use in PKIX Profile" [RFC4055].)
      • With ECDSA and the Digital Signature Standard (DSS), there is no way to extract the hash algorithm from the signature. Thus, for each new hash function to be supported with ECDSA or DSA, new authentication methods would be needed. Support for new hash functions is particularly needed for DSS, because the current restriction to SHA-1 limits its security, meaning there is no point of using long keys with SHA-1
      • The tying of ECDSA authentication methods to particular elliptic curve groups requires definition of additional methods for each new group. The combination of new ECDSA groups and hash functions will cause the number of required authentication methods to become unmanageable. Furthermore, the restriction of ECDSA authentication to a specific group is inconsistent with the approach taken with DSS
  • RESERVED - MUST be sent as zero; MUST be ignored on receipt
  • Authentication Data (variable length) - see Section 2.15
IKEv2 Authentication Method
DescriptionIdentifierAUTH Method
RSA AuthenticationAUTH_RSA1
Pre-Shared Key AuthenticationAUTH_PSK2
Digital Secure Signature AuthenticationAUTH_DSS3
Elliptic Curve with SHA-256 on the P-256 Curve AuthenticationAUTH_ECDSA_P2569
Elliptic Curve with SHA-384 on the P-384 Curve AuthenticationAUTH_ECDSA_P38410
Elliptic Curve with SHA-512 on the P-512 Curve AuthenticationAUTH_ECDSA_P51211
Generic Secure Password AuthenticationAUTH_GENERIC_SECURE_PASSWORD12
No PRF AuthenticationAUTH_NULL13
Digital Signature AuthenticationAUTH_DIGITAL_SIGNATURE14

Nonce Payload

Nonce Payload
  • Nonce Data (variable length) - Contains the random data generated by the transmitting entity

Notify Payload

Notify Payload
  • Protocol ID - If this notification concerns an existing SA whose SPI is given in the SPI field, this field indicates the type of that SA. For notifications concerning Child SAs, this field MUST contain either (2) to indicate AH or (3) to indicate ESP. Of the notifications defined in this document, the SPI is included only with INVALID_SELECTORS, REKEY_SA, and CHILD_SA_NOT_FOUND. If the SPI field is empty, this field MUST be sent as zero and MUST be ignored on receipt
  • SPI Size - Length in octets of the SPI as defined by the IPsec protocol ID or zero if no SPI is applicable. For a notification concerning the IKE SA, the SPI Size MUST be zero and the field must be empty
  • Notify Message Type - Specifies the type of notification message
  • SPI (variable length) - Security Parameter Index
  • Notification Data (variable length) - Status or error data transmitted in addition to the Notify Message Type. Values for this field are type specific (see below)

Delete Payload

Delete Payload
  • Protocol ID - Must be 1 for an IKE SA, 2 for AH, or 3 for ESP
  • SPI Size - Length in octets of the SPI as defined by the protocol ID. It MUST be zero for IKE (SPI is in message header) or four for AH and ESP
  • Num of SPIs (unsigned integer) - The number of SPIs contained in the Delete payload. The size of each SPI is defined by the SPI Size field
  • Security Parameter Index(es) (variable length) - Identifies the specific Security Association(s) to delete. The length of this field is determined by the SPI Size and Num of SPIs fields

Vendor ID Payload

Vendor ID Payload
  • Vendor ID (variable length) - It is the responsibility of the person choosing the Vendor ID to assure its uniqueness in spite of the absence of any central registry for IDs. Good practice is to include a company name, a person name, or some such information. If you want to show off, you might include the latitude and longitude and time where you were when you chose the ID and some random input. A message digest of a long unique string is preferable to the long unique string itself

Traffic Selectors Payload

Traffic Selectors Payload
  • Number of TSs - Number of Traffic Selectors being provided
  • RESERVED - This field MUST be sent as zero and MUST be ignored on receipt
  • Traffic Selectors (variable length) - One or more individual Traffic Selectors

Traffic Selector

Traffic Selector
  • TS Type - Specifies the type of Traffic Selector
    • TS_IPV4_ADDR_RANGE - A range of IPv4 addresses, represented by two four-octet values. The first value is the beginning IPv4 address (inclusive) and the second value is the ending IPv4 address (inclusive). All addresses falling between the two specified addresses are considered to be within the list
    • TS_IPV6_ADDR_RANGE - A range of IPv6 addresses, represented by two sixteen-octet values. The first value is the beginning IPv6 address (inclusive) and the second value is the ending IPv6 address (inclusive). All addresses falling between the two specified addresses are considered to be within the list
  • IP protocol ID - Value specifying an associated IP protocol ID (such as UDP, TCP, and ICMP). A value of zero means that the protocol ID is not relevant to this Traffic Selector - the SA can carry all protocols
  • Selector Length - Specifies the length of this Traffic Selector substructure including the header
  • Start Port - Value specifying the smallest port number allowed by this Traffic Selector. For protocols for which port is undefined (including protocol 0), or if all ports are allowed, this field MUST be zero. ICMP and ICMPv6 Type and Code values, as well as Mobile IP version 6 (MIPv6) mobility header (MH) Type values, are represented in this field as specified in Section 4.4.1.1 of [IPSECARCH]. ICMP Type and Code values are treated as a single 16-bit integer port number, with Type in the most significant eight bits and Code in the least significant eight bits. MIPv6 MH Type values are treated as a single 16-bit integer port number, with Type in the most significant eight bits and the least significant eight bits set to zero
  • End Port - Value specifying the largest port number allowed by this Traffic Selector. For protocols for which port is undefined (including protocol 0), or if all ports are allowed, this field MUST be 65535. ICMP and ICMPv6 Type and Code values, as well as MIPv6 MH Type values, are represented in this field as specified in Section 4.4.1.1 of [IPSECARCH]. ICMP Type and Code values are treated as a single 16-bit integer port number, with Type in the most significant eight bits and Code in the least significant eight bits. MIPv6 MH Type values are treated as a single 16-bit integer port number, with Type in the most significant eight bits and the least significant eight bits set to zero
  • Starting Address - The smallest address included in this Traffic Selector (length determined by TS Type)
  • Ending Address - The largest address included in this Traffic Selector (length determined by TS Type)

Encrypted Payload Format

Encrypted Payload Format
  • Next Payload - The payload type of the first embedded payload. Note that this is an exception in the standard header format, since the Encrypted payload is the last payload in the message and therefore the Next Payload field would normally be zero. But because the content of this payload is embedded payloads and there was no natural place to put the type of the first one, that type is placed here
  • Payload Length - Includes the lengths of the header, initialization vector (IV), Encrypted IKE payloads, Padding, Pad Length, and Integrity Checksum Data
  • Initialization Vector - For CBC mode ciphers, the length of the initialization vector (IV) is equal to the block length of the underlying encryption algorithm. Senders MUST select a new unpredictable IV for every message; recipients MUST accept any value. The reader is encouraged to consult [MODES] for advice on IV generation. In particular, using the final ciphertext block of the previous message is not considered unpredictable. For modes other than CBC, the IV format and processing is specified in the document specifying the encryption algorithm and mode
  • IKE payloads are as specified earlier in this section. This field is encrypted with the negotiated cipher
  • Padding MAY contain any value chosen by the sender, and MUST have a length that makes the combination of the payloads, the Padding, and the Pad Length to be a multiple of the encryption block size. This field is encrypted with the negotiated cipher
  • Pad Length is the length of the Padding field. The sender SHOULD set the Pad Length to the minimum value that makes the combination of the payloads, the Padding, and the Pad Length a multiple of the block size, but the recipient MUST accept any length that results in proper alignment. This field is encrypted with the negotiated cipher
  • Integrity Checksum Data is the cryptographic checksum of the entire message starting with the Fixed IKE header through the Pad Length. The checksum MUST be computed over the encrypted message. Its length is determined by the integrity algorithm negotiated

Configuration Payload

Configuration Payload
  • CFG Type - The type of exchange represented by the Configuration Attributes. The values in the following table are only current as of the publication date of RFC 4306. Other values may have been added since then or will be added after the publication of this document. Readers should refer to IANA.org for the latest values
    • CFG_REQUEST - 1
    • CFG_REPLY - 2
    • CFG_SET - 3
    • CFG_ACK - 4
  • RESERVED - MUST be sent as zero; MUST be ignored on receipt
  • Configuration Attributes (variable length) - These are type length value (TLV) structures specific to the Configuration payload and are defined below. There may be zero or more Configuration Attributes in this payload
IKEv2 Configuration Types
DescriptionIdentifierCFG Type
Request the configurationCFG_REQUEST1
Reply to a configuration requestCFG_REPLY2
Set the configurationCFG_SET3
Acknowledge the configuration requestCFG_ASK4

Configuration Attributes

Configuration Attribute Format
  • Reserved - This bit MUST be set to zero and MUST be ignored on receipt
  • Attribute Type - A unique identifier for each of the Configuration Attribute Types
  • Length - Length in octets of value
  • Value (0 or more octets) - The variable-length value of this Configuration Attribute. The following lists the attribute types
IKEv2 Configuration Attribute Types
DescriptionIdentifierCFG Attribute
Configure an internal IPv4 AddressCFG_INTERNAL_IP4_ADDRESS1
Configure an internal IPv4 NetmaskCFG_INTERNAL_IP4_NETMASK2
Configure an internal IPv4 Domain Name ServiceCFG_INTERNAL_IP4_DNS3
Configure an internal IPv4 NBNS settingCFG_INTERNAL_IP4_NBNS4
Configure an internal IPv4 DHCPCFG_INTERNAL_IP4_DHCP6
Configure application versionCFG_APPLICATION_VERSION7
Configure an internal IPv6 AddressCFG_INTERNAL_IP6_ADDRESS8
Configure an internal IPv6 Domain Name ServiceCFG_INTERNAL_IP6_DNS10
Configure an internal IPv6 DHCPCFG_INTERNAL_IP6_DHCP12
Configure an internal IPv4 SubnetCFG_INTERNAL_IP4_SUBNET13
Configure supported attributesCFG_SUPPORTED_ATTRIBUTES14
Configure an internal IPv6 SubnetCFG_INTERNAL_IP6_SUBNET15
Configure a MIP6 Home PrefixCFG_MIP6_HOME_PREFIX16
Configure an internal IPv6 LinkCFG_INTERNAL_IP6_LINK17
Configure an internal IPv6 PrefixCFG_INTERNAL_IP6_PREFIX18
Configure a Home Agent AddressCFG_HOME_AGENT_ADDR19
Configure a P CSCG IPv4 AddressCFG_P_CSCG_IP4_ADDR20
Configure a P CSCF IPv6 AddressCFG_P_CSCF_IP6_ADDR21
Configure a FTT KATCFG_FTT_KAT22
Configure an External Source IPv4 NAT InformationCFG_EXT_SRC_IP4_NAT23
Configure a Timeout Period for Liveness Check NumberCFG_TIMEOUT_LIVENESS24
Configure an Internal DNS DomainCFG_INTERNAL_DNS_DOMAIN25
Configure an Internal DNS Secure TACFG_INTERNAL_DNS_SEC_TA26

EAP Payload

EAP Payload Format

EAP Message

EAP Message Format
  • Code - Indicates whether this message is a Request (1), Response (2), Success (3), or Failure (4)
  • Identifier - Used in PPP to distinguish replayed messages from repeated ones. Since in IKE, EAP runs over a reliable protocol, the Identifier serves no function here. In a response message, this octet MUST be set to match the identifier in the corresponding request
  • Length - The length of the EAP message. MUST be four less than the Payload Length of the encapsulating payload
  • Type - Present only if the Code field is Request (1) or Response (2). For other codes, the EAP message length MUST be four octets and the Type and Type_Data fields MUST NOT be present. In a Request (1) message, Type indicates the data being requested. In a Response (2) message, Type MUST either be Nak or match the type of the data requested. Note that since IKE passes an indication of initiator identity in the first message in the IKE_AUTH exchange, the responder SHOULD NOT send EAP Identity requests (type 1). The initiator MAY, however, respond to such requests if it receives them
  • Type_Data (variable length) - Varies with the Type of Request and the associated Response. For the documentation of the EAP methods

IKEv2 State Diagram

IKEv2 State Diagram

For API Documentation:

See also
ProtocolPP::jsecass
ProtocolPP::jikev2sa
ProtocolPP::jprotocol
ProtocolPP::jikev2
ProtocolPP::jmodes
ProtocolPP::sm4

For Additional Documentation:

See also
jsecass
jikev2sa
jprotocol
jikev2
jmodes
sm4
Protocol++® (ProtocolPP®) written by : John Peter Greninger • © John Peter Greninger 2015-2024 • All Rights Reserved
All copyrights and trademarks are the property of their respective owners

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

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

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

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

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

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

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

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

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