Linux XFRM struct xfrm_state
In Linux XFRM subsystem, there are two main data structures used one for policy and another for state maintenance. This post explains the data structure used for xfrm state maintenance.
struct xfrm_state is defined by Linux XFRM subsystem is used for maintaining IPSEC SA information, also called as transformer information or xfrm state information. This data structure is defined in include/net/xfrm.h file.
“struct xfrm_state” defined in include/net/xfrm.h file:
I will explain some important fields of struct xfrm_state structure:
· id : XFRM state identity defined using struct xfrm_id which is the combination of destination IP address(daddr), SPI, protocol. This daddr field either contains daddr.a4 if IPv4 address or daddr.a6 if IPv6 address.
· sel : XFRM state selectors containing destination address, source address, destination port, source port and protocol information. Note this selectors information in this field may not be always available. Mostly filled in case of transport mode. These destination and source addresses can be a subnet or single IP. sel.family can have AF_INET and AF_INET6 values.
· props : XFRM state proposal or parameter information , contains encapsulation mode, replay window size, authentication algorithm, encryption algorithm, compression algorithm ,etc.
o props.aalgo can have the following values:
§ SADB_X_AALG_NULL, SADB_AALG_MD5HMAC, SADB_AALG_SHA1HMAC,SADB_X_AALG_SHA2_256HMAC, SADB_X_AALG_SHA2_384HMAC, SADB_X_AALG_SHA2_512HMAC, SADB_X_AALG_RIPEMD160HMAC, SADB_X_AALG_AES_XCBC_MAC
o props.ealgo can have the following values:
§ SADB_EALG_NULL, SADB_EALG_DESCBC, SADB_EALG_3DESCBC, SADB_X_EALG_CASTCBC, SADB_X_EALG_BLOWFISHCBC,SADB_X_EALG_AESCBC, SADB_X_EALG_SERPENTCBC, SADB_X_EALG_CAMELLIACBC, SADB_X_EALG_TWOFISHCBC, SADB_X_EALG_AESCTR
o props.calgo can have the following values:
§ SADB_X_CALG_DEFLATE, SADB_X_CALG_LZS, SADB_X_CALG_LZJH
o props.family can have AF_INET and AF_INET6 values.
o props.saddr.a4 of type struct in_addr will have source IPv4 address of SA
o props.saddr.a6 of type struct in6_addr will have source IPv6 address of SA
o props.mode indicates the encapsulation mode (XFRM_MODE_TRANSPORT, XFRM_MODE_TUNNEL, XFRM_MODE_BEET).
o props.reqid contain XFRM policy ID.
o props.flags can have the following flags:
§ XFRM_STATE_NOECN, XFRM_STATE_DECAP_DSCP, XFRM_STATE_NOPMTUDISC
· lft : XFRM state configured or negotiated lifetime information includes both soft life time and hard life time.
· aalg: authentication algorithm information having algorithm name(alg_name), ICV length in bits (alg_trunc_len), key length in bits and key values. alg_name can contain the following strings:
o “digest_null”, “hmac(md5)”, “hmac(sha1)”, “hmac(sha256)”, “hmac(sha384)”, “hmac(sha512)”, “hmac(rmd160)”, “xcbc(aes)”,”cmac(aes)”
· ealg: encryption algorithm information having algorithm name(alg_name), key length in bits (alg_key_len) and key values (alg_key). alg_name can contain the following strings:
o “ecb(cipher_null)”, “cbc(des)”, “cbc(des3_ede)”, “cbc(cast5)”, “cbc(blowfish)”, “cbc(aes)”, “cbc(serpent)”, “cbc(camellia)”, “cbc(twofish)”, “rfc3686(ctr(aes))”
· calg: compression algorithm information having algorithm name(alg_name), key length in bits (alg_key_len) and key values (alg_key). alg_name can contain the following strings:
o “deflate”, “lzs”,”lzjh”
· aead: aead algorithm information mainly used for combined modes having algorithm name, key length in bits(alg_key_len) and key values (alg_key) and ICV length in bits(alg_icv_len). alg_name can contain the following strings:
o “rfc4106(gcm(aes))”, “rfc4309(ccm(aes))”, “rfc4543(gcm(aes))”, “rfc7539esp(chacha20,poly1305)”
· geniv: for IV generation, can contain the following strings:
o “echainiv”, “seqiv”,
· tunnel: If IPCompression enabled , it points to IPIP tunnel for handling uncompressed packets.
· mark: This field has two m and v. (TBD)
· replay : field of struct xfrm_replay_state has following fields :
o oseq , seq , bitmap : used to maintain anti replay state
· replay_esn : field of struct xfrm_replay_state_esn has following fields:
o bmp_len , oseq, seq, oseq_hi, seq_hi, replay_window, bmp: used to maintain anti replay state when ESN enabled.
· encap: data type struct xfrm_encap_tmpl, will be non-null if NAT_T enabled. struct xfrm_encap_tmpl contains the following fields:
o encap_type : encapsulation type of values: UDP_ENCAP_ESPINUDP(=2)
o encap_sport : UDP encapsulated source port
o encap_dport : UDP encapsulated destination port
o encap_oa : currently set to 0
· preplay, preplay_esn: These fields store current replay states at the time of generating notification messages .
· repl: This structure (struct xfrm_replay) contains the callback functions pointers: advance, check, recheck, notify, overflow. These function pointers are assigned at __xfrm_init_state and xfrm_state_construct functions.
· replay_maxage, replay_maxdiff : If the current sequence number received and last max received sequence number difference is greater than replay_maxdiff field, notification is generated. For more info , refer to xfrm_replay.c
· rtimer: replay detection notification timer
· stats: statistics , struct xfrm_stats is used to define statistics , this statistics contain replay, replay_window and integrity_failed. Incremented in case of if received packet sequence number is duplicate (already received), if received packet sequence number is out of window , if there are ICV failures.
· curlft : current life time information, contains bytes, packets, add_time, use_time fields.
· xso : xfrm state offload information if xfrm state is offloaded in NIC ipsec offload functionality
· type_offload : struct xfrm_type_offload field keeps the function pointers to be called for outputting , input and transmit functionalities
· security : security context information.