From af1b556ee153f2e8ee3ca7ae477c9a0611488d00 Mon Sep 17 00:00:00 2001 From: Dan Williams Date: Tue, 5 Jul 2011 18:09:14 -0500 Subject: [PATCH] docs: update Wireless Security setting documentation --- libnm-util/nm-setting-wireless-security.c | 240 +++++++++++++++++++++- libnm-util/nm-setting-wireless-security.h | 42 +++- 2 files changed, 274 insertions(+), 8 deletions(-) diff --git a/libnm-util/nm-setting-wireless-security.c b/libnm-util/nm-setting-wireless-security.c index 3b4eba6f7a..585c263a5b 100644 --- a/libnm-util/nm-setting-wireless-security.c +++ b/libnm-util/nm-setting-wireless-security.c @@ -35,6 +35,36 @@ #include "nm-utils-private.h" #include "nm-setting-private.h" +/** + * SECTION:nm-setting-wireless-security + * @short_description: Describes connection properties for WiFi networks that + * use WEP, LEAP, WPA or WPA2/RSN security + * @include: nm-setting-wireless-security.h + * + * The #NMSettingWirelessSecurity object is a #NMSetting subclass that describes + * properties necessary for connection encrypted WiFi 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 WiFi 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 + **/ + +/** + * nm_setting_wired_error_quark: + * + * Registers an error quark for #NMSettingWired if necessary. + * + * Returns: the error quark used for #NMSettingWired errors. + **/ GQuark nm_setting_wireless_security_error_quark (void) { @@ -130,12 +160,25 @@ enum { LAST_PROP }; +/** + * nm_setting_wireless_security_new: + * + * Creates a new #NMSettingWirelessSecurity object with default values. + * + * Returns: (transfer full): the new empty #NMSettingWirelessSecurity object + **/ NMSetting * nm_setting_wireless_security_new (void) { return (NMSetting *) g_object_new (NM_TYPE_SETTING_WIRELESS_SECURITY, NULL); } +/** + * nm_setting_wireless_security_get_key_mgmt: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the #NMSettingWirelessSecurity:key-mgmt property of the setting + **/ const char * nm_setting_wireless_security_get_key_mgmt (NMSettingWirelessSecurity *setting) { @@ -144,6 +187,13 @@ nm_setting_wireless_security_get_key_mgmt (NMSettingWirelessSecurity *setting) return NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->key_mgmt; } +/** + * nm_setting_wireless_security_get_num_protos: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the number of security protocols this connection allows when + * connecting to secure WiFi networks + **/ guint32 nm_setting_wireless_security_get_num_protos (NMSettingWirelessSecurity *setting) { @@ -152,6 +202,13 @@ nm_setting_wireless_security_get_num_protos (NMSettingWirelessSecurity *setting) return g_slist_length (NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->proto); } +/** + * nm_setting_wireless_security_get_proto: + * @setting: the #NMSettingWirelessSecurity + * @i: an index into the protocol list + * + * Returns: the protocol at index @i + **/ const char * nm_setting_wireless_security_get_proto (NMSettingWirelessSecurity *setting, guint32 i) { @@ -165,6 +222,21 @@ nm_setting_wireless_security_get_proto (NMSettingWirelessSecurity *setting, guin return (const char *) g_slist_nth_data (priv->proto, i); } +/** + * nm_setting_wireless_security_add_proto: + * @setting: the #NMSettingWirelessSecurity + * @proto: the protocol to add, one of "wpa" or "rsn" + * + * Adds a WiFi 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 WiFi 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. + * + * Returns: %TRUE if the protocol was new and and was added to the allowed + * protocol list, or %FALSE if it was already in the list + **/ gboolean nm_setting_wireless_security_add_proto (NMSettingWirelessSecurity *setting, const char *proto) { @@ -176,7 +248,7 @@ nm_setting_wireless_security_add_proto (NMSettingWirelessSecurity *setting, cons priv = NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting); for (iter = priv->proto; iter; iter = g_slist_next (iter)) { - if (!strcmp (proto, (char *) iter->data)) + if (strcasecmp (proto, (char *) iter->data) == 0) return FALSE; } @@ -184,6 +256,13 @@ nm_setting_wireless_security_add_proto (NMSettingWirelessSecurity *setting, cons return TRUE; } +/** + * nm_setting_wireless_security_remove_proto: + * @setting: the #NMSettingWirelessSecurity + * @i: index of the protocol to remove + * + * Removes a protocol from the allowed protocol list. + **/ void nm_setting_wireless_security_remove_proto (NMSettingWirelessSecurity *setting, guint32 i) { @@ -200,6 +279,13 @@ nm_setting_wireless_security_remove_proto (NMSettingWirelessSecurity *setting, g priv->proto = g_slist_delete_link (priv->proto, elt); } +/** + * nm_setting_wireless_security_clear_protos: + * @setting: the #NMSettingWirelessSecurity + * + * Removes all protocols from the allowed list. If there are no protocols + * specified then all protocols are allowed. + **/ void nm_setting_wireless_security_clear_protos (NMSettingWirelessSecurity *setting) { @@ -212,6 +298,12 @@ nm_setting_wireless_security_clear_protos (NMSettingWirelessSecurity *setting) priv->proto = NULL; } +/** + * nm_setting_wireless_security_get_num_pairwise: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the number of pairwise encryption algorithms in the allowed list + **/ guint32 nm_setting_wireless_security_get_num_pairwise (NMSettingWirelessSecurity *setting) { @@ -220,6 +312,16 @@ nm_setting_wireless_security_get_num_pairwise (NMSettingWirelessSecurity *settin return g_slist_length (NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->pairwise); } +/** + * nm_setting_wireless_security_get_pairwise: + * @setting: the #NMSettingWirelessSecurity + * @i: index of an item in the allowed pairwise encryption algorithm list + * + * Returns the allowed pairwise encryption algorithm from allowed algorithm + * list. + * + * Returns: the pairwise encryption algorithm at index @i + **/ const char * nm_setting_wireless_security_get_pairwise (NMSettingWirelessSecurity *setting, guint32 i) { @@ -233,6 +335,20 @@ nm_setting_wireless_security_get_pairwise (NMSettingWirelessSecurity *setting, g return (const char *) g_slist_nth_data (priv->pairwise, i); } +/** + * nm_setting_wireless_security_add_pairwise: + * @setting: the #NMSettingWirelessSecurity + * @pairwise: the encryption algorithm to add, one of "wep40", "wep104", + * "tkip", or "ccmp" + * + * 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. + * + * Returns: %TRUE if the algorithm was added to the list, %FALSE if it was + * already in the list + **/ gboolean nm_setting_wireless_security_add_pairwise (NMSettingWirelessSecurity *setting, const char *pairwise) { @@ -244,7 +360,7 @@ nm_setting_wireless_security_add_pairwise (NMSettingWirelessSecurity *setting, c priv = NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting); for (iter = priv->pairwise; iter; iter = g_slist_next (iter)) { - if (!strcmp (pairwise, (char *) iter->data)) + if (strcasecmp (pairwise, (char *) iter->data) == 0) return FALSE; } @@ -252,6 +368,14 @@ nm_setting_wireless_security_add_pairwise (NMSettingWirelessSecurity *setting, c return TRUE; } +/** + * nm_setting_wireless_security_remove_pairwise: + * @setting: the #NMSettingWirelessSecurity + * @i: the index of an item in the allowed pairwise encryption algorithm list + * + * Removes an encryption algorithm from the allowed pairwise encryption + * algorithm list. + **/ void nm_setting_wireless_security_remove_pairwise (NMSettingWirelessSecurity *setting, guint32 i) { @@ -268,6 +392,13 @@ nm_setting_wireless_security_remove_pairwise (NMSettingWirelessSecurity *setting priv->pairwise = g_slist_delete_link (priv->pairwise, elt); } +/** + * nm_setting_wireless_security_clear_pairwise: + * @setting: the #NMSettingWirelessSecurity + * + * Removes all algorithms from the allowed list. If there are no algorithms + * specified then all pairwise encryption algorithms are allowed. + **/ void nm_setting_wireless_security_clear_pairwise (NMSettingWirelessSecurity *setting) { @@ -280,6 +411,12 @@ nm_setting_wireless_security_clear_pairwise (NMSettingWirelessSecurity *setting) priv->pairwise = NULL; } +/** + * nm_setting_wireless_security_get_num_groups: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the number of groupwise encryption algorithms in the allowed list + **/ guint32 nm_setting_wireless_security_get_num_groups (NMSettingWirelessSecurity *setting) { @@ -288,6 +425,16 @@ nm_setting_wireless_security_get_num_groups (NMSettingWirelessSecurity *setting) return g_slist_length (NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->group); } +/** + * nm_setting_wireless_security_get_group: + * @setting: the #NMSettingWirelessSecurity + * @i: index of an item in the allowed groupwise encryption algorithm list + * + * Returns the allowed groupwise encryption algorithm from allowed algorithm + * list. + * + * Returns: the groupwise encryption algorithm at index @i + **/ const char * nm_setting_wireless_security_get_group (NMSettingWirelessSecurity *setting, guint32 i) { @@ -301,6 +448,20 @@ nm_setting_wireless_security_get_group (NMSettingWirelessSecurity *setting, guin return (const char *) g_slist_nth_data (priv->group, i); } +/** + * nm_setting_wireless_security_add_group: + * @setting: the #NMSettingWirelessSecurity + * @group: the encryption algorithm to add, one of "wep40", "wep104", + * "tkip", or "ccmp" + * + * 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. + * + * Returns: %TRUE if the algorithm was added to the list, %FALSE if it was + * already in the list + **/ gboolean nm_setting_wireless_security_add_group (NMSettingWirelessSecurity *setting, const char *group) { @@ -312,7 +473,7 @@ nm_setting_wireless_security_add_group (NMSettingWirelessSecurity *setting, cons priv = NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting); for (iter = priv->group; iter; iter = g_slist_next (iter)) { - if (!strcmp (group, (char *) iter->data)) + if (strcasecmp (group, (char *) iter->data) == 0) return FALSE; } @@ -320,6 +481,14 @@ nm_setting_wireless_security_add_group (NMSettingWirelessSecurity *setting, cons return TRUE; } +/** + * nm_setting_wireless_security_remove_group: + * @setting: the #NMSettingWirelessSecurity + * @i: the index of an item in the allowed groupwise encryption algorithm list + * + * Removes an encryption algorithm from the allowed groupwise encryption + * algorithm list. + **/ void nm_setting_wireless_security_remove_group (NMSettingWirelessSecurity *setting, guint32 i) { @@ -336,6 +505,13 @@ nm_setting_wireless_security_remove_group (NMSettingWirelessSecurity *setting, g priv->group = g_slist_delete_link (priv->group, elt); } +/** + * nm_setting_wireless_security_clear_groups: + * @setting: the #NMSettingWirelessSecurity + * + * Removes all algorithms from the allowed list. If there are no algorithms + * specified then all groupwise encryption algorithms are allowed. + **/ void nm_setting_wireless_security_clear_groups (NMSettingWirelessSecurity *setting) { @@ -348,6 +524,12 @@ nm_setting_wireless_security_clear_groups (NMSettingWirelessSecurity *setting) priv->group = NULL; } +/** + * nm_setting_wireless_security_get_psk: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the #NMSettingWirelessSecurity:psk property of the setting + **/ const char * nm_setting_wireless_security_get_psk (NMSettingWirelessSecurity *setting) { @@ -371,6 +553,12 @@ nm_setting_wireless_security_get_psk_flags (NMSettingWirelessSecurity *setting) return NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->psk_flags; } +/** + * nm_setting_wireless_security_get_leap_username: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the #NMSettingWirelessSecurity:leap-username property of the setting + **/ const char * nm_setting_wireless_security_get_leap_username (NMSettingWirelessSecurity *setting) { @@ -379,6 +567,12 @@ nm_setting_wireless_security_get_leap_username (NMSettingWirelessSecurity *setti return NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->leap_username; } +/** + * nm_setting_wireless_security_get_leap_password: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the #NMSettingWirelessSecurity:leap-password property of the setting + **/ const char * nm_setting_wireless_security_get_leap_password (NMSettingWirelessSecurity *setting) { @@ -402,6 +596,13 @@ nm_setting_wireless_security_get_leap_password_flags (NMSettingWirelessSecurity return NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->leap_password_flags; } +/** + * nm_setting_wireless_security_get_wep_key: + * @setting: the #NMSettingWirelessSecurity + * @idx: the WEP key index (0..3 inclusive) + * + * Returns: the WEP key at the given index + **/ const char * nm_setting_wireless_security_get_wep_key (NMSettingWirelessSecurity *setting, guint32 idx) { @@ -424,6 +625,16 @@ nm_setting_wireless_security_get_wep_key (NMSettingWirelessSecurity *setting, gu return NULL; } +/** + * nm_setting_wireless_security_set_wep_key: + * @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 determiend by the value of the #NMSettingWirelessSecurity:wep-key-type + * property. + * + * Sets a WEP key in the given index. + **/ void nm_setting_wireless_security_set_wep_key (NMSettingWirelessSecurity *setting, guint32 idx, const char *key) { @@ -455,6 +666,12 @@ nm_setting_wireless_security_set_wep_key (NMSettingWirelessSecurity *setting, gu } } +/** + * nm_setting_wireless_security_get_wep_tx_keyidx: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the #NMSettingWirelessSecurity:wep-tx-keyidx property of the setting + **/ guint32 nm_setting_wireless_security_get_wep_tx_keyidx (NMSettingWirelessSecurity *setting) { @@ -463,6 +680,12 @@ nm_setting_wireless_security_get_wep_tx_keyidx (NMSettingWirelessSecurity *setti return NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->wep_tx_keyidx; } +/** + * nm_setting_wireless_security_get_auth_alg: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the #NMSettingWirelessSecurity:auth-alg property of the setting + **/ const char * nm_setting_wireless_security_get_auth_alg (NMSettingWirelessSecurity *setting) { @@ -485,6 +708,12 @@ nm_setting_wireless_security_get_wep_key_flags (NMSettingWirelessSecurity *setti return NM_SETTING_WIRELESS_SECURITY_GET_PRIVATE (setting)->wep_key_flags; } +/** + * nm_setting_wireless_security_get_wep_key_type: + * @setting: the #NMSettingWirelessSecurity + * + * Returns: the #NMSettingWirelessSecurity:wep-key-type property of the setting + **/ NMWepKeyType nm_setting_wireless_security_get_wep_key_type (NMSettingWirelessSecurity *setting) { @@ -1353,9 +1582,8 @@ nm_setting_wireless_security_class_init (NMSettingWirelessSecurityClass *setting /** * NMSettingWirelessSecurity:wep-key-type: * - * Controls the interpretation of WEP keys. Allowed values are 1 (interpret - * WEP keys as hexadecimal or ASCII keys) or 2 (interpret WEP keys as WEP - * Passphrases). If set to 1 and the keys are hexadecimal, they must be + * Controls the interpretation of WEP keys. Allowed values are those given + * by %NMWepKeyType. If set to 1 and the keys are hexadecimal, they must be * either 10 or 26 characters in length. If set to 1 and the keys are * ASCII keys, they must be either 5 or 13 characters in length. If set to * 2, the passphrase is hashed using the de-facto MD5 method to derive the diff --git a/libnm-util/nm-setting-wireless-security.h b/libnm-util/nm-setting-wireless-security.h index 743e161f02..5f23893aa2 100644 --- a/libnm-util/nm-setting-wireless-security.h +++ b/libnm-util/nm-setting-wireless-security.h @@ -39,8 +39,23 @@ G_BEGIN_DECLS #define NM_SETTING_WIRELESS_SECURITY_SETTING_NAME "802-11-wireless-security" -typedef enum -{ +/** + * NMSettingWirelessSecurityError: + * @NM_SETTING_WIRELESS_SECURITY_ERROR_UNKNOWN: unknown or unclassified error + * @NM_SETTING_WIRELESS_SECURITY_ERROR_INVALID_PROPERTY: the property was invalid + * @NM_SETTING_WIRELESS_SECURITY_ERROR_MISSING_PROPERTY: the property was + * missing and is required + * @NM_SETTING_WIRELESS_SECURITY_ERROR_MISSING_802_1X_SETTING: a property contained + * a value that requires the connection to contain a #NMSetting8021x setting + * @NM_SETTING_WIRELESS_SECURITY_ERROR_LEAP_REQUIRES_802_1X: LEAP authentication + * was specified but key management was not set to "8021x" + * @NM_SETTING_WIRELESS_SECURITY_ERROR_LEAP_REQUIRES_USERNAME: LEAP authentication + * was specified but no LEAP username was given + * @NM_SETTING_WIRELESS_SECURITY_ERROR_SHARED_KEY_REQUIRES_WEP: Shared Key + * authentication was specified but the setting did not specify WEP as the + * encryption protocol + */ +typedef enum { NM_SETTING_WIRELESS_SECURITY_ERROR_UNKNOWN = 0, NM_SETTING_WIRELESS_SECURITY_ERROR_INVALID_PROPERTY, NM_SETTING_WIRELESS_SECURITY_ERROR_MISSING_PROPERTY, @@ -56,6 +71,29 @@ GType nm_setting_wireless_security_error_get_type (void); #define NM_SETTING_WIRELESS_SECURITY_ERROR nm_setting_wireless_security_error_quark () GQuark nm_setting_wireless_security_error_quark (void); +/** + * NMWepKeyType: + * @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 + * + * The #NMWepKeyType values specify how any WEP keys present in the setting + * are intepreted. 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, requring 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. + */ typedef enum { NM_WEP_KEY_TYPE_UNKNOWN = 0, NM_WEP_KEY_TYPE_KEY = 1, /* Hex or ASCII */