libnm: update documentation for 802-1x ca-cert, ca-path and system-ca-certs

2 files changed, 38 insertions, 20 deletions

diff --git a/clients/common/settings-docs.h.in b/clients/common/settings-docs.h.in
index b51d0a1ecf..2ae2377813 100644
--- a/clients/common/settings-docs.h.in
+++ b/clients/common/settings-docs.h.in
@@ -44,10 +44,10 @@
 #define DESCRIBE_DOC_NM_SETTING_802_1X_ALTSUBJECT_MATCHES N_("List of strings to be matched against the altSubjectName of the certificate presented by the authentication server. If the list is empty, no verification of the server certificate's altSubjectName is performed.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_ANONYMOUS_IDENTITY N_("Anonymous identity string for EAP authentication methods.  Used as the unencrypted identity with EAP types that support different tunneled identity like EAP-TTLS.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_AUTH_TIMEOUT N_("A timeout for the authentication. Zero means the global default; if the global default is not set, the authentication timeout is 25 seconds.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_CA_CERT N_("Contains the CA certificate if used by the EAP method specified in the \"eap\" property. Certificate data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme (which is backwards compatible with NM 0.7.x) this property should be set to the certificate's DER encoded data. When using the path scheme, this property should be set to the full UTF-8 encoded path of the certificate, prefixed with the string \"file://\" and ending with a terminating NUL byte. This property can be unset even if the EAP method supports CA certificates, but this allows man-in-the-middle attacks and is NOT recommended.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_CA_CERT N_("Contains the CA certificate if used by the EAP method specified in the \"eap\" property. Certificate data is specified using a \"scheme\"; three are currently supported: blob, path and pkcs#11 URL. When using the blob scheme this property should be set to the certificate's DER encoded data. When using the path scheme, this property should be set to the full UTF-8 encoded path of the certificate, prefixed with the string \"file://\" and ending with a terminating NUL byte. This property can be unset even if the EAP method supports CA certificates, but this allows man-in-the-middle attacks and is NOT recommended. Note that enabling NMSetting8021x:system-ca-certs will override this setting to use the built-in path, if the built-in path is not a directory.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_CA_CERT_PASSWORD N_("The password used to access the CA certificate stored in \"ca-cert\" property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_CA_CERT_PASSWORD_FLAGS N_("Flags indicating how to handle the \"ca-cert-password\" property.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_CA_PATH N_("UTF-8 encoded path to a directory containing PEM or DER formatted certificates to be added to the verification chain in addition to the certificate specified in the \"ca-cert\" property.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_CA_PATH N_("UTF-8 encoded path to a directory containing PEM or DER formatted certificates to be added to the verification chain in addition to the certificate specified in the \"ca-cert\" property. If NMSetting8021x:system-ca-certs is enabled and the built-in CA path is an existing directory, then this setting is ignored.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_CLIENT_CERT N_("Contains the client certificate if used by the EAP method specified in the \"eap\" property. Certificate data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme (which is backwards compatible with NM 0.7.x) this property should be set to the certificate's DER encoded data. When using the path scheme, this property should be set to the full UTF-8 encoded path of the certificate, prefixed with the string \"file://\" and ending with a terminating NUL byte.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_CLIENT_CERT_PASSWORD N_("The password used to access the client certificate stored in \"client-cert\" property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_CLIENT_CERT_PASSWORD_FLAGS N_("Flags indicating how to handle the \"client-cert-password\" property.")
@@ -68,10 +68,10 @@
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_ALTSUBJECT_MATCHES N_("List of strings to be matched against the altSubjectName of the certificate presented by the authentication server during the inner \"phase 2\" authentication. If the list is empty, no verification of the server certificate's altSubjectName is performed.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_AUTH N_("Specifies the allowed \"phase 2\" inner non-EAP authentication method when an EAP method that uses an inner TLS tunnel is specified in the \"eap\" property.  Recognized non-EAP \"phase 2\" methods are \"pap\", \"chap\", \"mschap\", \"mschapv2\", \"gtc\", \"otp\", \"md5\", and \"tls\". Each \"phase 2\" inner method requires specific parameters for successful authentication; see the wpa_supplicant documentation for more details.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_AUTHEAP N_("Specifies the allowed \"phase 2\" inner EAP-based authentication method when an EAP method that uses an inner TLS tunnel is specified in the \"eap\" property.  Recognized EAP-based \"phase 2\" methods are \"md5\", \"mschapv2\", \"otp\", \"gtc\", and \"tls\". Each \"phase 2\" inner method requires specific parameters for successful authentication; see the wpa_supplicant documentation for more details.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CA_CERT N_("Contains the \"phase 2\" CA certificate if used by the EAP method specified in the \"phase2-auth\" or \"phase2-autheap\" properties. Certificate data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme (which is backwards compatible with NM 0.7.x) this property should be set to the certificate's DER encoded data. When using the path scheme, this property should be set to the full UTF-8 encoded path of the certificate, prefixed with the string \"file://\" and ending with a terminating NUL byte. This property can be unset even if the EAP method supports CA certificates, but this allows man-in-the-middle attacks and is NOT recommended.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CA_CERT N_("Contains the \"phase 2\" CA certificate if used by the EAP method specified in the \"phase2-auth\" or \"phase2-autheap\" properties. Certificate data is specified using a \"scheme\"; three are currently supported: blob, path and pkcs#11 URL. When using the blob scheme this property should be set to the certificate's DER encoded data. When using the path scheme, this property should be set to the full UTF-8 encoded path of the certificate, prefixed with the string \"file://\" and ending with a terminating NUL byte. This property can be unset even if the EAP method supports CA certificates, but this allows man-in-the-middle attacks and is NOT recommended. Note that enabling NMSetting8021x:system-ca-certs will override this setting to use the built-in path, if the built-in path is not a directory.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CA_CERT_PASSWORD N_("The password used to access the \"phase2\" CA certificate stored in \"phase2-ca-cert\" property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CA_CERT_PASSWORD_FLAGS N_("Flags indicating how to handle the \"phase2-ca-cert-password\" property.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CA_PATH N_("UTF-8 encoded path to a directory containing PEM or DER formatted certificates to be added to the verification chain in addition to the certificate specified in the \"phase2-ca-cert\" property.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CA_PATH N_("UTF-8 encoded path to a directory containing PEM or DER formatted certificates to be added to the verification chain in addition to the certificate specified in the \"phase2-ca-cert\" property. If NMSetting8021x:system-ca-certs is enabled and the built-in CA path is an existing directory, then this setting is ignored.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CLIENT_CERT N_("Contains the \"phase 2\" client certificate if used by the EAP method specified in the \"phase2-auth\" or \"phase2-autheap\" properties. Certificate data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme (which is backwards compatible with NM 0.7.x) this property should be set to the certificate's DER encoded data. When using the path scheme, this property should be set to the full UTF-8 encoded path of the certificate, prefixed with the string \"file://\" and ending with a terminating NUL byte. This property can be unset even if the EAP method supports CA certificates, but this allows man-in-the-middle attacks and is NOT recommended.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CLIENT_CERT_PASSWORD N_("The password used to access the \"phase2\" client certificate stored in \"phase2-client-cert\" property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_CLIENT_CERT_PASSWORD_FLAGS N_("Flags indicating how to handle the \"phase2-client-cert-password\" property.")
diff --git a/libnm-core/nm-setting-8021x.c b/libnm-core/nm-setting-8021x.c
index ade34ff554..0d614d4fa1 100644
--- a/libnm-core/nm-setting-8021x.c
+++ b/libnm-core/nm-setting-8021x.c
@@ -3576,15 +3576,18 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *klass)
 	 * Contains the CA certificate if used by the EAP method specified in the
 	 * #NMSetting8021x:eap property.
 	 *
-	 * Certificate data is specified using a "scheme"; two are currently
-	 * supported: blob and path. When using the blob scheme (which is backwards
-	 * compatible with NM 0.7.x) this property should be set to the
-	 * certificate's DER encoded data. When using the path scheme, this property
-	 * should be set to the full UTF-8 encoded path of the certificate, prefixed
-	 * with the string "file://" and ending with a terminating NUL byte. This
-	 * property can be unset even if the EAP method supports CA certificates,
+	 * Certificate data is specified using a "scheme"; three are currently
+	 * supported: blob, path and pkcs#11 URL. When using the blob scheme this property
+	 * should be set to the certificate's DER encoded data. When using the path
+	 * scheme, this property should be set to the full UTF-8 encoded path of the
+	 * certificate, prefixed with the string "file://" and ending with a terminating
+	 * NUL byte.
+	 * This property can be unset even if the EAP method supports CA certificates,
 	 * but this allows man-in-the-middle attacks and is NOT recommended.
 	 *
+	 * Note that enabling NMSetting8021x:system-ca-certs will override this
+	 * setting to use the built-in path, if the built-in path is not a directory.
+	 *
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_ca_cert() function instead.
 	 **/
@@ -3643,11 +3646,14 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *klass)
 	 * UTF-8 encoded path to a directory containing PEM or DER formatted
 	 * certificates to be added to the verification chain in addition to the
 	 * certificate specified in the #NMSetting8021x:ca-cert property.
+	 *
+	 * If NMSetting8021x:system-ca-certs is enabled and the built-in CA
+	 * path is an existing directory, then this setting is ignored.
 	 **/
 	/* ---ifcfg-rh---
 	 * property: ca-path
-	 * variable: (none)
-	 * description: The property is not handled by ifcfg-rh plugin.
+	 * variable: IEEE_8021X_CA_PATH(+)
+	 * description: The search path for the certificate.
 	 * ---end---
 	 */
 	obj_properties[PROP_CA_PATH] =
@@ -3964,15 +3970,18 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *klass)
 	 * in the #NMSetting8021x:phase2-auth or #NMSetting8021x:phase2-autheap
 	 * properties.
 	 *
-	 * Certificate data is specified using a "scheme"; two are currently
-	 * supported: blob and path. When using the blob scheme (which is backwards
-	 * compatible with NM 0.7.x) this property should be set to the
-	 * certificate's DER encoded data. When using the path scheme, this property
-	 * should be set to the full UTF-8 encoded path of the certificate, prefixed
-	 * with the string "file://" and ending with a terminating NUL byte. This
-	 * property can be unset even if the EAP method supports CA certificates,
+	 * Certificate data is specified using a "scheme"; three are currently
+	 * supported: blob, path and pkcs#11 URL. When using the blob scheme this property
+	 * should be set to the certificate's DER encoded data. When using the path
+	 * scheme, this property should be set to the full UTF-8 encoded path of the
+	 * certificate, prefixed with the string "file://" and ending with a terminating
+	 * NUL byte.
+	 * This property can be unset even if the EAP method supports CA certificates,
 	 * but this allows man-in-the-middle attacks and is NOT recommended.
 	 *
+	 * Note that enabling NMSetting8021x:system-ca-certs will override this
+	 * setting to use the built-in path, if the built-in path is not a directory.
+	 *
 	 * Setting this property directly is discouraged; use the
 	 * nm_setting_802_1x_set_phase2_ca_cert() function instead.
 	 **/
@@ -4024,7 +4033,16 @@ nm_setting_802_1x_class_init (NMSetting8021xClass *klass)
 	 * UTF-8 encoded path to a directory containing PEM or DER formatted
 	 * certificates to be added to the verification chain in addition to the
 	 * certificate specified in the #NMSetting8021x:phase2-ca-cert property.
+	 *
+	 * If NMSetting8021x:system-ca-certs is enabled and the built-in CA
+	 * path is an existing directory, then this setting is ignored.
 	 **/
+	/* ---ifcfg-rh---
+	 * property: phase2-ca-path
+	 * variable: IEEE_8021X_PHASE2_CA_PATH(+)
+	 * description: The search path for the certificate.
+	 * ---end---
+	 */
 	obj_properties[PROP_PHASE2_CA_PATH] =
 	    g_param_spec_string (NM_SETTING_802_1X_PHASE2_CA_PATH, "", "",
 	                         NULL,