NMSettingWirelessSecurity: libnm Reference Manual

NMSettingWirelessSecurity

NMSettingWirelessSecurity — Describes connection properties for Wi-Fi networks that use WEP, LEAP, WPA or WPA2/RSN security

Functions

NMSetting *	nm_setting_wireless_security_new ()
const char *	nm_setting_wireless_security_get_key_mgmt ()
guint32	nm_setting_wireless_security_get_num_protos ()
const char *	nm_setting_wireless_security_get_proto ()
gboolean	nm_setting_wireless_security_add_proto ()
void	nm_setting_wireless_security_remove_proto ()
gboolean	nm_setting_wireless_security_remove_proto_by_value ()
void	nm_setting_wireless_security_clear_protos ()
guint32	nm_setting_wireless_security_get_num_pairwise ()
const char *	nm_setting_wireless_security_get_pairwise ()
gboolean	nm_setting_wireless_security_add_pairwise ()
void	nm_setting_wireless_security_remove_pairwise ()
gboolean	nm_setting_wireless_security_remove_pairwise_by_value ()
void	nm_setting_wireless_security_clear_pairwise ()
guint32	nm_setting_wireless_security_get_num_groups ()
const char *	nm_setting_wireless_security_get_group ()
gboolean	nm_setting_wireless_security_add_group ()
void	nm_setting_wireless_security_remove_group ()
gboolean	nm_setting_wireless_security_remove_group_by_value ()
void	nm_setting_wireless_security_clear_groups ()
NMSettingWirelessSecurityPmf	nm_setting_wireless_security_get_pmf ()
const char *	nm_setting_wireless_security_get_psk ()
NMSettingSecretFlags	nm_setting_wireless_security_get_psk_flags ()
const char *	nm_setting_wireless_security_get_leap_username ()
const char *	nm_setting_wireless_security_get_leap_password ()
NMSettingSecretFlags	nm_setting_wireless_security_get_leap_password_flags ()
const char *	nm_setting_wireless_security_get_wep_key ()
void	nm_setting_wireless_security_set_wep_key ()
guint32	nm_setting_wireless_security_get_wep_tx_keyidx ()
const char *	nm_setting_wireless_security_get_auth_alg ()
NMSettingSecretFlags	nm_setting_wireless_security_get_wep_key_flags ()
NMWepKeyType	nm_setting_wireless_security_get_wep_key_type ()
NMSettingWirelessSecurityWpsMethod	nm_setting_wireless_security_get_wps_method ()
NMSettingWirelessSecurityFils	nm_setting_wireless_security_get_fils ()

Types and Values

#define	NM_SETTING_WIRELESS_SECURITY_SETTING_NAME
enum	NMWepKeyType
enum	NMSettingWirelessSecurityPmf
enum	NMSettingWirelessSecurityWpsMethod
enum	NMSettingWirelessSecurityFils
#define	NM_SETTING_WIRELESS_SECURITY_KEY_MGMT
#define	NM_SETTING_WIRELESS_SECURITY_WEP_TX_KEYIDX
#define	NM_SETTING_WIRELESS_SECURITY_AUTH_ALG
#define	NM_SETTING_WIRELESS_SECURITY_PROTO
#define	NM_SETTING_WIRELESS_SECURITY_PAIRWISE
#define	NM_SETTING_WIRELESS_SECURITY_GROUP
#define	NM_SETTING_WIRELESS_SECURITY_PMF
#define	NM_SETTING_WIRELESS_SECURITY_LEAP_USERNAME
#define	NM_SETTING_WIRELESS_SECURITY_WEP_KEY0
#define	NM_SETTING_WIRELESS_SECURITY_WEP_KEY1
#define	NM_SETTING_WIRELESS_SECURITY_WEP_KEY2
#define	NM_SETTING_WIRELESS_SECURITY_WEP_KEY3
#define	NM_SETTING_WIRELESS_SECURITY_WEP_KEY_FLAGS
#define	NM_SETTING_WIRELESS_SECURITY_WEP_KEY_TYPE
#define	NM_SETTING_WIRELESS_SECURITY_PSK
#define	NM_SETTING_WIRELESS_SECURITY_PSK_FLAGS
#define	NM_SETTING_WIRELESS_SECURITY_LEAP_PASSWORD
#define	NM_SETTING_WIRELESS_SECURITY_LEAP_PASSWORD_FLAGS
#define	NM_SETTING_WIRELESS_SECURITY_WPS_METHOD
#define	NM_SETTING_WIRELESS_SECURITY_FILS

Object Hierarchy

    GEnum
    ├── NMSettingWirelessSecurityFils
    ├── NMSettingWirelessSecurityPmf
    ╰── NMWepKeyType
    GFlags
    ╰── NMSettingWirelessSecurityWpsMethod

Description

The NMSettingWirelessSecurity object is a NMSetting subclass that describes properties necessary for connection to encrypted Wi-Fi networks.

It's a good idea to read up on wpa_supplicant configuration before using this setting extensively, since most of the options here correspond closely with the relevant wpa_supplicant configuration options. To get a better overview of how Wi-Fi security works, you may want to get copies of the following books.

802.11 Wireless Networks: The Definitive Guide, Second Edition Author: Matthew Gast ISBN: 978-0596100520

Cisco Wireless LAN Security Authors: Krishna Sankar, Sri Sundaralingam, Darrin Miller, and Andrew Balinsky ISBN: 978-1587051548

Functions

nm_setting_wireless_security_new ()

NMSetting *
nm_setting_wireless_security_new (void);

Creates a new NMSettingWirelessSecurity object with default values.

Returns

the new empty NMSettingWirelessSecurity object.

[transfer full]

nm_setting_wireless_security_get_key_mgmt ()

const char *
nm_setting_wireless_security_get_key_mgmt
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “key-mgmt” property of the setting

nm_setting_wireless_security_get_num_protos ()

guint32
nm_setting_wireless_security_get_num_protos
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the number of security protocols this connection allows when connecting to secure Wi-Fi networks

nm_setting_wireless_security_get_proto ()

const char *
nm_setting_wireless_security_get_proto
                               (NMSettingWirelessSecurity *setting,
                                guint32 i);

Parameters

setting	the NMSettingWirelessSecurity
i	an index into the protocol list

Returns

the protocol at index i

nm_setting_wireless_security_add_proto ()

gboolean
nm_setting_wireless_security_add_proto
                               (NMSettingWirelessSecurity *setting,
                                const char *proto);

Adds a Wi-Fi security protocol (one of "wpa" or "rsn") to the allowed list; only protocols in this list will be used when finding and connecting to the Wi-Fi network specified by this connection. For example, if the protocol list contains only "wpa" but the access point for the SSID specified by this connection only supports WPA2/RSN, the connection cannot be used with the access point.

Parameters

setting	the NMSettingWirelessSecurity
proto	the protocol to add, one of "wpa" or "rsn"

Returns

TRUE if the protocol was new and was added to the allowed protocol list, or FALSE if it was already in the list

nm_setting_wireless_security_remove_proto ()

void
nm_setting_wireless_security_remove_proto
                               (NMSettingWirelessSecurity *setting,
                                guint32 i);

Removes a protocol from the allowed protocol list.

Parameters

setting	the NMSettingWirelessSecurity
i	index of the protocol to remove

nm_setting_wireless_security_remove_proto_by_value ()

gboolean
nm_setting_wireless_security_remove_proto_by_value
                               (NMSettingWirelessSecurity *setting,
                                const char *proto);

Removes a protocol from the allowed protocol list.

Parameters

setting	the NMSettingWirelessSecurity
proto	the protocol to remove, one of "wpa" or "rsn"

Returns

TRUE if the protocol was found and removed; FALSE if it was not.

nm_setting_wireless_security_clear_protos ()

void
nm_setting_wireless_security_clear_protos
                               (NMSettingWirelessSecurity *setting);

Removes all protocols from the allowed list. If there are no protocols specified then all protocols are allowed.

Parameters

setting

the NMSettingWirelessSecurity

nm_setting_wireless_security_get_num_pairwise ()

guint32
nm_setting_wireless_security_get_num_pairwise
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the number of pairwise encryption algorithms in the allowed list

nm_setting_wireless_security_get_pairwise ()

const char *
nm_setting_wireless_security_get_pairwise
                               (NMSettingWirelessSecurity *setting,
                                guint32 i);

Returns the allowed pairwise encryption algorithm from allowed algorithm list.

Parameters

setting	the NMSettingWirelessSecurity
i	index of an item in the allowed pairwise encryption algorithm list

Returns

the pairwise encryption algorithm at index i

nm_setting_wireless_security_add_pairwise ()

gboolean
nm_setting_wireless_security_add_pairwise
                               (NMSettingWirelessSecurity *setting,
                                const char *pairwise);

Adds an encryption algorithm to the list of allowed pairwise encryption algorithms. If the list is not empty, then only access points that support one or more of the encryption algorithms in the list will be considered compatible with this connection.

Parameters

setting	the NMSettingWirelessSecurity
pairwise	the encryption algorithm to add, one of "tkip" or "ccmp"

Returns

TRUE if the algorithm was added to the list, FALSE if it was already in the list

nm_setting_wireless_security_remove_pairwise ()

void
nm_setting_wireless_security_remove_pairwise
                               (NMSettingWirelessSecurity *setting,
                                guint32 i);

Removes an encryption algorithm from the allowed pairwise encryption algorithm list.

Parameters

setting	the NMSettingWirelessSecurity
i	the index of an item in the allowed pairwise encryption algorithm list

nm_setting_wireless_security_remove_pairwise_by_value ()

gboolean
nm_setting_wireless_security_remove_pairwise_by_value
                               (NMSettingWirelessSecurity *setting,
                                const char *pairwise);

Removes an encryption algorithm from the allowed pairwise encryption algorithm list.

Parameters

setting	the NMSettingWirelessSecurity
pairwise	the encryption algorithm to remove, one of "tkip" or "ccmp"

Returns

TRUE if the encryption algorithm was found and removed; FALSE if it was not.

nm_setting_wireless_security_clear_pairwise ()

void
nm_setting_wireless_security_clear_pairwise
                               (NMSettingWirelessSecurity *setting);

Removes all algorithms from the allowed list. If there are no algorithms specified then all pairwise encryption algorithms are allowed.

Parameters

setting

the NMSettingWirelessSecurity

nm_setting_wireless_security_get_num_groups ()

guint32
nm_setting_wireless_security_get_num_groups
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the number of groupwise encryption algorithms in the allowed list

nm_setting_wireless_security_get_group ()

const char *
nm_setting_wireless_security_get_group
                               (NMSettingWirelessSecurity *setting,
                                guint32 i);

Returns the allowed groupwise encryption algorithm from allowed algorithm list.

Parameters

setting	the NMSettingWirelessSecurity
i	index of an item in the allowed groupwise encryption algorithm list

Returns

the groupwise encryption algorithm at index i

nm_setting_wireless_security_add_group ()

gboolean
nm_setting_wireless_security_add_group
                               (NMSettingWirelessSecurity *setting,
                                const char *group);

Adds an encryption algorithm to the list of allowed groupwise encryption algorithms. If the list is not empty, then only access points that support one or more of the encryption algorithms in the list will be considered compatible with this connection.

Parameters

setting	the NMSettingWirelessSecurity
group	the encryption algorithm to add, one of "wep40", "wep104", "tkip", or "ccmp"

Returns

TRUE if the algorithm was added to the list, FALSE if it was already in the list

nm_setting_wireless_security_remove_group ()

void
nm_setting_wireless_security_remove_group
                               (NMSettingWirelessSecurity *setting,
                                guint32 i);

Removes an encryption algorithm from the allowed groupwise encryption algorithm list.

Parameters

setting	the NMSettingWirelessSecurity
i	the index of an item in the allowed groupwise encryption algorithm list

nm_setting_wireless_security_remove_group_by_value ()

gboolean
nm_setting_wireless_security_remove_group_by_value
                               (NMSettingWirelessSecurity *setting,
                                const char *group);

Removes an encryption algorithm from the allowed groupwise encryption algorithm list.

Parameters

setting	the NMSettingWirelessSecurity
group	the encryption algorithm to remove, one of "wep40", "wep104", "tkip", or "ccmp"

Returns

TRUE if the algorithm was found and removed; FALSE if it was not.

nm_setting_wireless_security_clear_groups ()

void
nm_setting_wireless_security_clear_groups
                               (NMSettingWirelessSecurity *setting);

Removes all algorithms from the allowed list. If there are no algorithms specified then all groupwise encryption algorithms are allowed.

Parameters

setting

the NMSettingWirelessSecurity

nm_setting_wireless_security_get_pmf ()

NMSettingWirelessSecurityPmf
nm_setting_wireless_security_get_pmf (NMSettingWirelessSecurity *setting);

nm_setting_wireless_security_get_psk ()

const char *
nm_setting_wireless_security_get_psk (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “psk” property of the setting

nm_setting_wireless_security_get_psk_flags ()

NMSettingSecretFlags
nm_setting_wireless_security_get_psk_flags
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the NMSettingSecretFlags pertaining to the “psk”

nm_setting_wireless_security_get_leap_username ()

const char *
nm_setting_wireless_security_get_leap_username
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “leap-username” property of the setting

nm_setting_wireless_security_get_leap_password ()

const char *
nm_setting_wireless_security_get_leap_password
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “leap-password” property of the setting

nm_setting_wireless_security_get_leap_password_flags ()

NMSettingSecretFlags
nm_setting_wireless_security_get_leap_password_flags
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the NMSettingSecretFlags pertaining to the “leap-password”

nm_setting_wireless_security_get_wep_key ()

const char *
nm_setting_wireless_security_get_wep_key
                               (NMSettingWirelessSecurity *setting,
                                guint32 idx);

Parameters

setting	the NMSettingWirelessSecurity
idx	the WEP key index (0..3 inclusive)

Returns

the WEP key at the given index

nm_setting_wireless_security_set_wep_key ()

void
nm_setting_wireless_security_set_wep_key
                               (NMSettingWirelessSecurity *setting,
                                guint32 idx,
                                const char *key);

Sets a WEP key in the given index.

Parameters

setting	the NMSettingWirelessSecurity
idx	the index of the key (0..3 inclusive)
key	the WEP key as a string, in either hexadecimal, ASCII, or passphrase form as determined by the value of the “wep-key-type” property.

nm_setting_wireless_security_get_wep_tx_keyidx ()

guint32
nm_setting_wireless_security_get_wep_tx_keyidx
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “wep-tx-keyidx” property of the setting

nm_setting_wireless_security_get_auth_alg ()

const char *
nm_setting_wireless_security_get_auth_alg
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “auth-alg” property of the setting

nm_setting_wireless_security_get_wep_key_flags ()

NMSettingSecretFlags
nm_setting_wireless_security_get_wep_key_flags
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the NMSettingSecretFlags pertaining to the all WEP keys

nm_setting_wireless_security_get_wep_key_type ()

NMWepKeyType
nm_setting_wireless_security_get_wep_key_type
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “wep-key-type” property of the setting

nm_setting_wireless_security_get_wps_method ()

NMSettingWirelessSecurityWpsMethod
nm_setting_wireless_security_get_wps_method
                               (NMSettingWirelessSecurity *setting);

Parameters

setting

the NMSettingWirelessSecurity

Returns

the “wps-method” property of the setting

Since: 1.10

nm_setting_wireless_security_get_fils ()

NMSettingWirelessSecurityFils
nm_setting_wireless_security_get_fils (NMSettingWirelessSecurity *setting);

Types and Values

NM_SETTING_WIRELESS_SECURITY_SETTING_NAME

#define NM_SETTING_WIRELESS_SECURITY_SETTING_NAME "802-11-wireless-security"

enum NMWepKeyType

The NMWepKeyType values specify how any WEP keys present in the setting are interpreted. There are no standards governing how to hash the various WEP key/passphrase formats into the actual WEP key. Unfortunately some WEP keys can be interpreted in multiple ways, requiring the setting to specify how to interpret the any WEP keys. For example, the key "732f2d712e4a394a375d366931" is both a valid Hexadecimal WEP key and a WEP passphrase. Further, many ASCII keys are also valid WEP passphrases, but since passphrases and ASCII keys are hashed differently to determine the actual WEP key the type must be specified.

Members

NM_WEP_KEY_TYPE_UNKNOWN	unknown WEP key type
NM_WEP_KEY_TYPE_KEY	indicates a hexadecimal or ASCII formatted WEP key. Hex keys are either 10 or 26 hexadecimal characters (ie "5f782f2f5f" or "732f2d712e4a394a375d366931"), while ASCII keys are either 5 or 13 ASCII characters (ie "abcde" or "blahblah99$*1").
NM_WEP_KEY_TYPE_PASSPHRASE	indicates a WEP passphrase (ex "I bought a duck on my way back from the market 235Q&^%^*%") instead of a hexadecimal or ASCII key. Passphrases are between 8 and 64 characters inclusive and are hashed the actual WEP key using the MD5 hash algorithm.
NM_WEP_KEY_TYPE_LAST	placeholder value for bounds-checking

enum NMSettingWirelessSecurityPmf

These flags indicate whether PMF must be enabled.

Members

NM_SETTING_WIRELESS_SECURITY_PMF_DEFAULT	use the default value
NM_SETTING_WIRELESS_SECURITY_PMF_DISABLE	disable PMF
NM_SETTING_WIRELESS_SECURITY_PMF_OPTIONAL	enable PMF if the supplicant and the AP support it
NM_SETTING_WIRELESS_SECURITY_PMF_REQUIRED	require PMF and fail if not available
_NM_SETTING_WIRELESS_SECURITY_PMF_NUM
NM_SETTING_WIRELESS_SECURITY_PMF_LAST

enum NMSettingWirelessSecurityWpsMethod

Configure the use of WPS by a connection while it activates.

Note: prior to 1.16, this was a GEnum type instead of a GFlags type although, with the same numeric values.

Members

NM_SETTING_WIRELESS_SECURITY_WPS_METHOD_DEFAULT	Attempt whichever method AP supports
NM_SETTING_WIRELESS_SECURITY_WPS_METHOD_DISABLED	WPS can not be used.
NM_SETTING_WIRELESS_SECURITY_WPS_METHOD_AUTO	Use WPS, any method
NM_SETTING_WIRELESS_SECURITY_WPS_METHOD_PBC	use WPS push-button method
NM_SETTING_WIRELESS_SECURITY_WPS_METHOD_PIN	use PIN method

Since: 1.10

enum NMSettingWirelessSecurityFils

These flags indicate whether FILS must be enabled.

Members

NM_SETTING_WIRELESS_SECURITY_FILS_DEFAULT	use the default value
NM_SETTING_WIRELESS_SECURITY_FILS_DISABLE	disable FILS
NM_SETTING_WIRELESS_SECURITY_FILS_OPTIONAL	enable FILS if the supplicant and the AP support it
NM_SETTING_WIRELESS_SECURITY_FILS_REQUIRED	require FILS and fail if not available
_NM_SETTING_WIRELESS_SECURITY_FILS_NUM	placeholder value for bounds-checking
NM_SETTING_WIRELESS_SECURITY_FILS_LAST	placeholder value for bounds-checking

Since: 1.12

NM_SETTING_WIRELESS_SECURITY_KEY_MGMT

#define NM_SETTING_WIRELESS_SECURITY_KEY_MGMT            "key-mgmt"

NM_SETTING_WIRELESS_SECURITY_WEP_TX_KEYIDX

#define NM_SETTING_WIRELESS_SECURITY_WEP_TX_KEYIDX       "wep-tx-keyidx"

NM_SETTING_WIRELESS_SECURITY_AUTH_ALG

#define NM_SETTING_WIRELESS_SECURITY_AUTH_ALG            "auth-alg"

NM_SETTING_WIRELESS_SECURITY_PROTO

#define NM_SETTING_WIRELESS_SECURITY_PROTO               "proto"

NM_SETTING_WIRELESS_SECURITY_PAIRWISE

#define NM_SETTING_WIRELESS_SECURITY_PAIRWISE            "pairwise"

NM_SETTING_WIRELESS_SECURITY_GROUP

#define NM_SETTING_WIRELESS_SECURITY_GROUP               "group"

NM_SETTING_WIRELESS_SECURITY_PMF

#define NM_SETTING_WIRELESS_SECURITY_PMF                 "pmf"

NM_SETTING_WIRELESS_SECURITY_LEAP_USERNAME

#define NM_SETTING_WIRELESS_SECURITY_LEAP_USERNAME       "leap-username"

NM_SETTING_WIRELESS_SECURITY_WEP_KEY0

#define NM_SETTING_WIRELESS_SECURITY_WEP_KEY0            "wep-key0"

NM_SETTING_WIRELESS_SECURITY_WEP_KEY1

#define NM_SETTING_WIRELESS_SECURITY_WEP_KEY1            "wep-key1"

NM_SETTING_WIRELESS_SECURITY_WEP_KEY2

#define NM_SETTING_WIRELESS_SECURITY_WEP_KEY2            "wep-key2"

NM_SETTING_WIRELESS_SECURITY_WEP_KEY3

#define NM_SETTING_WIRELESS_SECURITY_WEP_KEY3            "wep-key3"

NM_SETTING_WIRELESS_SECURITY_WEP_KEY_FLAGS

#define NM_SETTING_WIRELESS_SECURITY_WEP_KEY_FLAGS       "wep-key-flags"

NM_SETTING_WIRELESS_SECURITY_WEP_KEY_TYPE

#define NM_SETTING_WIRELESS_SECURITY_WEP_KEY_TYPE        "wep-key-type"

NM_SETTING_WIRELESS_SECURITY_PSK

#define NM_SETTING_WIRELESS_SECURITY_PSK                 "psk"

NM_SETTING_WIRELESS_SECURITY_PSK_FLAGS

#define NM_SETTING_WIRELESS_SECURITY_PSK_FLAGS           "psk-flags"

NM_SETTING_WIRELESS_SECURITY_LEAP_PASSWORD

#define NM_SETTING_WIRELESS_SECURITY_LEAP_PASSWORD       "leap-password"

NM_SETTING_WIRELESS_SECURITY_LEAP_PASSWORD_FLAGS

#define NM_SETTING_WIRELESS_SECURITY_LEAP_PASSWORD_FLAGS "leap-password-flags"

NM_SETTING_WIRELESS_SECURITY_WPS_METHOD

#define NM_SETTING_WIRELESS_SECURITY_WPS_METHOD          "wps-method"

NM_SETTING_WIRELESS_SECURITY_FILS

#define NM_SETTING_WIRELESS_SECURITY_FILS                "fils"