xref: /freebsd/contrib/wpa/src/common/proximity_ranging.h (revision 71e72c9e91c4b8007a4292e09669e8b549c29e97)

/*
 * Proxmity Ranging
 * Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
 *
 * This software may be distributed under the terms of the BSD license.
 * See README for more details.
 */

#ifndef PROXIMITY_RANGING_H
#define PROXIMITY_RANGING_H

#include "wpa_common.h"
#include "utils/list.h"
#include "wps/wps_defs.h"

struct ieee80211_mgmt;

#define DEVICE_IDENTITY_KEY_LEN 16
#define DEVICE_IDENTITY_TAG_LEN 8
#define DEVICE_IDENTITY_NONCE_LEN 8
#define DIR_STR_LEN 3
#define DEVICE_MAX_HASH_LEN 32

/* DIRA Cipher versions */
#define DIRA_CIPHER_VERSION_128 0

/**
 * PR_MAX_OP_CLASSES - Maximum number of operating classes
 */
#define PR_MAX_OP_CLASSES 30

/**
 * PR_MAX_OP_CLASS_CHANNELS - Maximum number of channels per operating class
 */
#define PR_MAX_OP_CLASS_CHANNELS 60

/**
 * PR_MAX_PEER - Maximum number of Proximity Ranging peers that device can store
 */
#define PR_MAX_PEER 100

/*
 * Proximity Ranging negotiation status
 * Proximity Ranging Implementation Considerations for P2P Operation D1.8,
 * Table 5 (Proximity Ranging Status Attribute format).
 */
#define PR_NEGOTIATION_SUCCESS 0
#define PR_NEGOTIATION_UPDATE 1
#define PR_NEGOTIATION_FAIL 2

/**
 * enum pr_session_end_reason - Reason codes for ranging session end
 */
enum pr_session_end_reason {
	PR_SESSION_END_TIMEOUT       = 0,
	PR_SESSION_END_USER_ABORT    = 1,
	PR_SESSION_END_PEER_COMPLETE = 2,
	PR_SESSION_END_NEG_FAILED    = 3,
};

enum pr_pasn_role {
	PR_ROLE_IDLE = 0,
	PR_ROLE_PASN_INITIATOR,
	PR_ROLE_PASN_RESPONDER,
};

/**
 * struct pr_channels - List of supported channels
 */
struct pr_channels {
	/**
	 * struct pr_op_class - Supported operating class
	 */
	struct pr_op_class {
		/**
		 * op_class - Operating class
		 */
		u8 op_class;

		/**
		 * channel - Supported channels
		 */
		u8 channel[PR_MAX_OP_CLASS_CHANNELS];

		/**
		 * channels - Number of channel entries in use
		 */
		size_t channels;
	} op_class[PR_MAX_OP_CLASSES];

	/**
	 * op_classes - Number of op_class entries in use
	 */
	size_t op_classes;
};

/**
 * Format and Bandwidth values for EDCA based ranging with range of 10-16
 * from IEEE Std 802.11-2024, 9.4.2.166 (FTM Parameters element), Table 9-325
 * (Format And Bandwidth subfield) as specified in Proximity Ranging
 * Implementation Considerations for P2P Operation, Draft 1.8, Table 8
 * (Proximity Ranging EDCA Capability Attribute format) for the the Ranging
 * Parameters field B0-B3.
 */
enum edca_format_and_bw_value {
	EDCA_FORMAT_AND_BW_VHT20 = 10,
	EDCA_FORMAT_AND_BW_HT40 = 11,
	EDCA_FORMAT_AND_BW_VHT40 = 12,
	EDCA_FORMAT_AND_BW_VHT80 = 13,
	EDCA_FORMAT_AND_BW_VHT80P80 = 14,
	EDCA_FORMAT_AND_BW_VHT160_DUAL_LO = 15,
	EDCA_FORMAT_AND_BW_VHT160_SINGLE_LO = 16,
	EDCA_FORMAT_AND_BW_INVALID
};

/**
 * Format and Bandwidth values for NTB based ranging as from IEEE Std
 * 802.11-2024, 9.4.2.300 (Ranging Parameters element), Table 9-412 (Format And
 * Bandwidth subfield) as specified in Proximity Ranging Implementation
 * Considerations for P2P Operation, Draft 1.8, Table 9 (Proximity Ranging 11az
 * NTB Capability Attribute format) for the Ranging Parameter field B0-B2.
 */
enum ntb_format_and_bw_value {
	NTB_FORMAT_AND_BW_HE20 = 0,
	NTB_FORMAT_AND_BW_HE40 = 1,
	NTB_FORMAT_AND_BW_HE80 = 2,
	NTB_FORMAT_AND_BW_HE80P80 = 3,
	NTB_FORMAT_AND_BW_HE160_DUAL_LO = 4,
	NTB_FORMAT_AND_BW_HE160_SINGLE_LO = 5,
	NTB_FORMAT_AND_BW_INVALID
};

struct pr_capabilities {
	u8 pasn_type;

	char device_name[WPS_DEV_NAME_MAX_LEN + 1];

	bool edca_support;

	bool ntb_support;

	bool secure_he_ltf;

	bool support_6ghz;
};

struct edca_capabilities {
	bool ista_support;

	bool rsta_support;

/**
 * Ranging Parameters field for device specific EDCA capabilities
 * Proximity Ranging Implementation Considerations for P2P Operation Draft 1.8,
 * Table 8 (Proximity Ranging EDCA Capability Attribute format).
 */
#define EDCA_FORMAT_AND_BW  0
#define EDCA_MAX_TX_ANTENNA 4
#define EDCA_MAX_RX_ANTENNA 7

#define EDCA_FORMAT_AND_BW_MASK  0x000F
#define EDCA_MAX_TX_ANTENNA_MASK 0x0007
#define EDCA_MAX_RX_ANTENNA_MASK 0x0007
	u16 edca_hw_caps;

	char country[3];

	struct pr_channels channels;
};

struct ntb_capabilities {
	bool ista_support;

	bool rsta_support;

	bool secure_he_ltf;

/**
 * Ranging Parameter field for NTB capabilities
 * Proximity Ranging Implementation Considerations for P2P Operation Draft 1.8,
 * Table 9 (Proximity Ranging 11az NTB Capability Attribute format).
 */
#define NTB_FORMAT_AND_BW	0
#define MAX_TX_LTF_REPETATIONS	3
#define MAX_RX_LTF_REPETATIONS	6
#define MAX_RX_LTF_TOTAL	9
#define MAX_TX_LTF_TOTAL	11
#define MAX_RX_STS_LE_80	13
#define MAX_RX_STS_GT_80	16
#define MAX_TX_STS_LE_80	19
#define MAX_TX_STS_GT_80	22

#define NTB_FORMAT_AND_BW_MASK  0x00000007

/* Max TX LTF repetations supported for non trigger based ranging */
#define MAX_TX_LTF_REPETATIONS_MASK	0x00000007

/* Max RX LTF repetations supported for non trigger based ranging */
#define MAX_RX_LTF_REPETATIONS_MASK	0x00000007

/* Max RX LTF total supported for non trigger based ranging */
#define MAX_RX_LTF_TOTAL_MASK		0x00000003

/* Max TX LTF total supported for non trigger based ranging */
#define MAX_TX_LTF_TOTAL_MASK		0x00000003

/* To configure max R2I STS for Bandwidth less than or equal to 80 MHz */
#define MAX_RX_STS_LE_80_MASK		0x00000007

/* To configure max R2I STS for Bandwidth greater than 80Mz */
#define MAX_RX_STS_GT_80_MASK		0x00000007

/* To configure max I2R STS for Bandwidth less than or equal to 80 MHz */
#define MAX_TX_STS_LE_80_MASK		0x00000007

/* To configure max I2R STS for Bandwidth greater than 80 MHz */
#define MAX_TX_STS_GT_80_MASK		0x00000007
	u32 ntb_hw_caps;

	char country[3];

	struct pr_channels channels;
};

/*
 * Proximity Ranging Attribute IDs
 * Proximity Ranging Implementation Considerations for P2P Operation Draft 1.8,
 * Table 4 (Proximity Ranging Attribute ID list).
 */
enum pr_attr_id {
	PR_ATTR_STATUS = 0,
	PR_ATTR_RANGING_CAPABILITY = 1,
	PR_ATTR_EDCA_CAPABILITY = 2,
	PR_ATTR_NTB_CAPABILITY = 3,
	PR_ATTR_OPERATION_MODE = 4,
	PR_ATTR_WLAN_AP_INFO = 5,
	PR_ATTR_DEVICE_IDENTITY_RESOLUTION = 6,
	PR_ATTR_VENDOR_SPECIFIC = 221,
};

/*
 * Proximity Ranging capabilities in Ranging Protocol Type field,
 * Proximity Ranging Implementation Considerations for P2P Operation Draft 1.8,
 * Table 7 (Proximity Ranging Capability Attribute format).
 */
#define PR_EDCA_BASED_RANGING BIT(0)
#define PR_NTB_SECURE_LTF_BASED_RANGING BIT(1)
#define PR_NTB_OPEN_BASED_RANGING BIT(2)

/**
 * Ranging Role field in EDCA capabilities
 * Proximity Ranging Implementation Considerations for P2P Operation Draft 1.8,
 * Table 8 (Proximity Ranging EDCA Capability Attribute format).
 */
#define PR_ISTA_SUPPORT BIT(0)
#define PR_RSTA_SUPPORT BIT(1)

/*
 * PASN capabilities in PASN Type field
 * Proximity Ranging Implementation Considerations for P2P Operation D1.8,
 * Table 7 (Proximity Ranging Capability Attribute).
 */
#define PR_PASN_DH19_UNAUTH BIT(0)
#define PR_PASN_DH19_AUTH BIT(1)
#define PR_PASN_DH20_UNAUTH BIT(2)
#define PR_PASN_DH20_AUTH BIT(3)

/* Authentication Mode */
#define PR_PASN_AUTH_MODE_PASN   0
#define PR_PASN_AUTH_MODE_SAE    1
#define PR_PASN_AUTH_MODE_PMK    2

/* Peer discovery type */
#define PR_DISCOVERY_TYPE_USD    0
#define PR_DISCOVERY_TYPE_OOB    1

/**
 * struct pr_pasn_ranging_params - Peer parameters to be used in PASN to trigger
 * ranging in case PR PASN is successful.
 */
struct pr_pasn_ranging_params {
	enum {
		PR_PASN_AND_RANGING,
		PR_STOP_RANGING,
	} action;
	u8 peer_addr[ETH_ALEN];
	u8 ranging_type;
	u8 ranging_role;
	u8 pr_pasn_status;
	u8 auth_mode;
	int freq;
	u32 ranging_timeout;
	u8 src_addr[ETH_ALEN];
	enum pr_pasn_role pasn_role;

	/**
	 * EDCA based ranging specific parameters
	 *
	 * @burst_period: Burst period in units of 100 milliseconds
	 * @num_bursts_exp: Number of bursts exponent
	 * @ftms_per_burst: Number of FTM frames per burst
	 * @ftmr_retries: Number of retries for FTM Request frame
	 * @burst_duration: Burst duration as defined in IEEE Std 802.11-2024,
	 *  Table 9-322 (Burst Duration subfield encoding).
	 */
	u16 burst_period;
	u8 num_bursts_exp;
	u8 ftms_per_burst;
	u8 ftmr_retries;
	u8 burst_duration;

	/**
	 * NTB ranging specific parameters
	 *
	 * @min_time_between_measurements: Minimum time between two consecutive
	 *  range measurements in units of 100 microseconds.
	 * @max_time_between_measurements: Maximum time between two consecutive
	 *  range measurements in units of 10 milliseconds, to avoid FTM
	 *  negotiation.
	 * @availability_window: Duration of the Availability Window (AW) in
	 *  units of 1 millisecond (0-255 ms).
	 * @nominal_time: Nominal duration between adjacent Availability Windows
	 *  in units of milliseconds.
	 */
	u32 min_time_between_measurements;
	u32 max_time_between_measurements;
	u8 availability_window;
	u32 nominal_time;

	/**
	 * @request_lci: Whether to request LCI
	 * @request_civicloc: Whether to request civic location
	 */
	bool request_lci;
	bool request_civicloc;

	/**
	 * @lmr_feedback: Negotiate LMR feedback for NTB ranging.
	 * Only valid when NTB ranging type is set. Required for RSTA
	 * to report measurement results back to the initiator.
	 */
	bool lmr_feedback;

	/**
	 * @ingress_threshold: Ingress range threshold in millimeters.
	 * The kernel reports a measurement result when the device
	 * moves into this range.
	 */
	u64 ingress_threshold;

	/**
	 * @egress_threshold: Egress range threshold in millimeters.
	 * The kernel reports a measurement result when the device
	 * moves out of this range.
	 */
	u64 egress_threshold;

	/**
	 * @pr_suppress_results: Suppress ranging results for PD requests.
	 * Cannot be used with range_report or lmr_feedback.
	 */
	bool pr_suppress_results;

	u32 continuous_ranging_session_time;

	int forced_pr_freq;
	u8 ranging_op_class;
	u16 channel_width; /* channel width in MHz (20/40/80/160/320) */
	u8 format_bw;
	u32 center_freq1;
	u32 center_freq2;
	u64 cookie;

	/* Per-session credentials - if set, used instead of stored ones */
	char password[100];
	bool password_valid;
	u8 pmk[PMK_LEN_MAX];
	size_t pmk_len;
};

struct pr_dev_ik {
	struct dl_list list;
	u8 dik[DEVICE_IDENTITY_KEY_LEN];
	char password[100];
	bool password_valid;
	u8 pmk[PMK_LEN_MAX];
	size_t pmk_len;
	bool pmk_valid;
};

/**
 * struct pr_device_info - Proximity ranging peer information
 */
struct pr_device {
	struct dl_list list;
	struct os_reltime last_seen;
	int listen_freq;

	/**
	 * pr_device_addr - PR Device Address of the peer
	 */
	u8 pr_device_addr[ETH_ALEN];

	struct pr_capabilities pr_caps;
	struct edca_capabilities edca_caps;
	struct ntb_capabilities ntb_caps;

	/* Password to be used in PASN-SAE by the Seeker.
	 * This is updated with valid password if DIRA matches for the peer.
	 */
	char password[100];
	bool password_valid;

	/* PMK to be used in PASN-PMK by the Seeker.
	 * This is updated with valid PMK if DIRA matches for the peer.
	 */
	u8 pmk[PMK_LEN_MAX];
	size_t pmk_len;
	bool pmk_valid;

	/* DevIK of the peer resolved via DIRA verification.
	 * Set to the matched dev_ik->dik when pr_validate_dira() succeeds.
	 * Cleared by pr_clear_dev_iks().
	 */
	u8 dik[DEVICE_IDENTITY_KEY_LEN];
	bool dik_valid;

#ifdef CONFIG_PASN
	/* PASN data structure */
	struct pasn_data *pasn;
	struct wpabuf *ranging_wrapper;
	enum pr_pasn_role pasn_role;
#endif /* CONFIG_PASN */

	u8 ranging_role;
	u8 protocol_type;
	u8 final_op_class;
	u8 final_op_channel;
	u8 discovery_type;
};


/**
 * struct pr_message - Proximity ranging peer information
 */
struct pr_message {
	struct wpabuf *pr_attributes;

	u8 pr_device_addr[ETH_ALEN];

	const u8 *pr_capability;
	size_t pr_capability_len;

	const u8 *edca_capability;
	size_t edca_capability_len;

	const u8 *ntb_capability;
	size_t ntb_capability_len;

	const u8 *dira;
	size_t dira_len;

	const u8 *status_ie;
	size_t status_ie_len;

	const u8 *op_mode;
	size_t op_mode_len;
};


struct pr_config {
	u8 pasn_type;

	int preferred_ranging_role;

	char country[3];

	u8 dev_addr[ETH_ALEN];

	/**
	 * dev_name - Device Name
	 */
	char *dev_name;

	bool edca_ista_support;

	bool edca_rsta_support;

	/* Best single format_bw value derived from pd_format_bw_bitmap */
	u8 edca_format_and_bw;

	u32 edca_min_ranging_interval;

	u8 max_tx_antenna;

	u8 max_rx_antenna;

	struct pr_channels edca_channels;

	bool ntb_ista_support;

	bool ntb_rsta_support;

	bool concurrent_ista_rsta;

	u32 pmsr_max_peers;

	u32 pr_max_peer_ista_role;

	u32 pr_max_peer_rsta_role;

	u8 max_ftms_per_burst;

	bool secure_he_ltf;

	u8 max_tx_ltf_repetations;

	u8 max_rx_ltf_repetations;

	u8 max_tx_ltf_total;

	u8 max_rx_ltf_total;

	u8 max_rx_sts_le_80;

	u8 max_rx_sts_gt_80;

	u8 max_tx_sts_le_80;

	u8 max_tx_sts_gt_80;

	/* PD ranging preamble and bandwidth bitmaps (shared by EDCA and NTB) */
	u32 pd_preamble_bitmap;
	u32 pd_format_bw_bitmap;

	/* Best single format_bw value derived from pd_format_bw_bitmap */
	u8 ntb_format_and_bw;

	u32 ntb_min_ranging_interval;

	struct pr_channels ntb_channels;

	bool support_6ghz;

	/* Cipher version type */
	int dik_cipher;

	/* Buffer to hold the DevIK */
	u8 dik_data[DEVICE_IDENTITY_KEY_LEN];

	/* Length of DevIK in octets */
	size_t dik_len;

	/* DevIK expiration */
	int expiration;

	/* Global password to be used in PASN-SAE for Advertiser */
	char global_password[100];

	bool global_password_valid;

	/**
	 * cb_ctx - Context to use with callback functions
	 */
	void *cb_ctx;

	/**
	 * pasn_send_mgmt - Function handler to transmit a Management frame
	 * @ctx: Callback context from cb_ctx
	 * @data: Frame to transmit
	 * @data_len: Length of frame to transmit
	 * @noack: No ack flag
	 * @freq: Frequency in MHz for the channel on which to transmit
	 * @wait: How many milliseconds to wait for a response frame
	 * Returns: 0 on success, -1 on failure
	 */
	int (*pasn_send_mgmt)(void *ctx, const u8 *data, size_t data_len,
			      int noack, unsigned int freq, unsigned int wait);

	/**
	 * negotiation_started - Called when PASN negotiation begins
	 * @ctx: Callback context from cb_ctx
	 * @peer_addr: MAC address of the peer
	 * @role: Ranging role (initiator or responder)
	 * @protocol_type: Ranging protocol type
	 *
	 * Fired on the initiator after Auth frame 1 (M1) is sent, and on the
	 * responder after Auth frame 1 (M1) is received and M2 is sent back.
	 */
	void (*negotiation_started)(void *ctx, const u8 *peer_addr, u8 role,
				    u8 protocol_type);

	void (*pasn_result)(void *ctx, u8 role, u8 protocol_type, u8 op_class,
			    u8 op_channel, const char *country);

	int (*set_keys)(void *ctx, const u8 *own_addr, const u8 *peer_addr,
			int cipher, int akmp, struct wpa_ptk *ptk);

	void (*clear_keys)(void *ctx, const u8 *own_addr, const u8 *peer_addr);

	void (*get_ranging_params)(void *ctx, const u8 *dev_addr,
				   const u8 *peer_addr, u8 ranging_role,
				   u8 protocol_type, u8 op_class, u8 op_channel,
				   u8 self_format_bw, u8 peer_format_bw);

	void (*device_found)(void *ctx, const struct pr_device *dev);
};

struct pr_data {
	/**
	 * cfg - PR module configuration
	 *
	 * This is included in the same memory allocation with the
	 * struct pr_data and as such, must not be freed separately.
	 */
	struct pr_config *cfg;

	struct dl_list devices;

	struct dl_list dev_iks;

	/* PMKSA cache for PASN-PMK authentication */
	struct rsn_pmksa_cache *initiator_pmksa;
	struct rsn_pmksa_cache *responder_pmksa;

	/* PR PASN request tracking - similar to pasn_params in wpa_supplicant
	 */
	struct pr_pasn_ranging_params *pr_pasn_params;

	/* Set when final measurement result received; blocks further results */
	bool ranging_final_received;
};

/* PR Device Identity Resolution Attribute parameters */
struct pr_dira {
	/* Cipher version type */
	int cipher_version;
	/* Nonce used in DIRA attribute */
	u8 nonce[DEVICE_IDENTITY_NONCE_LEN];
	/* Length of nonce */
	size_t nonce_len;
	/* Tag computed for nonce using NIK */
	u8 tag[DEVICE_IDENTITY_TAG_LEN];
	/* Length of tag in octets */
	size_t tag_len;
};

struct operation_mode {
	/* Bitmap for Ranging Protocol type */
	u8 protocol_type;

	/* Bitmap for Role-ISTA/RSTA */
	u8 role;

	char country[3];

	struct pr_channels channels;
};

struct pr_data * pr_init(const struct pr_config *cfg);
void pr_flush(struct pr_data *pr);
void pr_deinit(struct pr_data *pr);
void pr_set_dev_addr(struct pr_data *pr, const u8 *addr);
void pr_clear_dev_iks(struct pr_data *pr);
void pr_add_dev_ik(struct pr_data *pr, const u8 *dik, const char *password,
		   const u8 *pmk, size_t pmk_len, bool own);
int pr_set_peer_credentials(struct pr_data *pr, const u8 *addr,
			    const u8 *pmk, size_t pmk_len,
			    const char *password);
struct wpabuf * pr_prepare_usd_elems(struct pr_data *pr, const u8 *src_addr);
void pr_process_usd_elems(struct pr_data *pr, const u8 *ies, u16 ies_len,
			  const u8 *peer_addr, unsigned int freq);
int pr_ensure_oob_peer(struct pr_data *pr, const u8 *addr, int freq);
int pr_initiate_pasn_auth(struct pr_data *pr, const u8 *addr, int freq,
			  u8 auth_mode, u8 ranging_role, u8 ranging_type,
			  int forced_pr_freq);
int pr_pasn_auth_tx_status(struct pr_data *pr, const u8 *data, size_t data_len,
			   bool acked);
int pr_pasn_auth_retransmit(struct pr_data *pr, const u8 *addr);
int pr_pasn_auth_rx(struct pr_data *pr, const struct ieee80211_mgmt *mgmt,
		    size_t len, int freq);

#endif /* PROXIMITY_RANGING_H */