merge: branch 'ih/802-1x_cert_doc'main

doc: remove explanations about certificate schemes from nmcli

Closes #1479

https://gitlab.freedesktop.org/NetworkManager/NetworkManager/-/merge_requests/1926

4 files changed, 87 insertions, 48 deletions

diff --git a/src/libnm-core-impl/nm-setting-8021x.c b/src/libnm-core-impl/nm-setting-8021x.c
index 55105e6920..4ea6072966 100644
--- a/src/libnm-core-impl/nm-setting-8021x.c
+++ b/src/libnm-core-impl/nm-setting-8021x.c
@@ -3335,6 +3335,19 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * Setting this property directly is discouraged; use the
      * nm_setting_802_1x_set_ca_cert() function instead.
      **/
+    /* ---nmcli---
+     * property: ca-cert
+     * description:
+     *   Contains the path to the CA certificate if used by the EAP method
+     *   specified in the 802-1x.eap property.
+     *
+     *   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 802-1x.system-ca-certs will override this
+     *   setting to use the built-in path, if the built-in path is not a directory.
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: ca-cert
      * variable: IEEE_8021X_CA_CERT(+)
@@ -3525,6 +3538,13 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * Setting this property directly is discouraged; use the
      * nm_setting_802_1x_set_client_cert() function instead.
      **/
+    /* ---nmcli---
+     * property: client-cert
+     * description:
+     *   Contains the path to the client certificate if used by the EAP method
+     *   specified in the 802-1x.eap property.
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: client-cert
      * variable: IEEE_8021X_CLIENT_CERT(+)
@@ -3765,6 +3785,20 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * Setting this property directly is discouraged; use the
      * nm_setting_802_1x_set_phase2_ca_cert() function instead.
      **/
+    /* ---nmcli---
+     * property: phase2-ca-cert
+     * description:
+     *   Contains the path to the "phase 2" CA certificate if used by the EAP
+     *   method specified in the 802-1x.phase2-auth or 802-1x.phase2-autheap
+     *   properties.
+     *
+     *   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 802-1x.system-ca-certs will override this
+     *   setting to use the built-in path, if the built-in path is not a directory.
+     * ---end---
+     */
     _nm_setting_property_define_direct_bytes(properties_override,
                                              obj_properties,
                                              NM_SETTING_802_1X_PHASE2_CA_CERT,
@@ -3953,6 +3987,14 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * Setting this property directly is discouraged; use the
      * nm_setting_802_1x_set_phase2_client_cert() function instead.
      **/
+    /* ---nmcli---
+     * property: phase2-client-cert
+     * description:
+     *   Contains the path to the "phase 2" client certificate if used by the EAP
+     *   method specified in the 802-1x.phase2-auth or 802-1x.phase2-autheap
+     *   properties.
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: phase2-client-cert
      * variable: IEEE_8021X_INNER_CLIENT_CERT(+)
@@ -4116,6 +4158,12 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * private key password to prevent unauthorized access to unencrypted
      * private key data.
      **/
+    /* ---nmcli---
+     * property: private-key
+     * description:
+     *   The path to the private key when the 802-1.eap property is set to "tls".
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: private-key
      * variable: IEEE_8021X_PRIVATE_KEY(+)
@@ -4141,6 +4189,14 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * secrets to NetworkManager; it is generally set automatically when setting
      * the private key by the nm_setting_802_1x_set_private_key() function.
      **/
+    /* ---nmcli---
+     * property: private-key-password
+     * description:
+     *   The password used to decrypt the private key specified in the
+     *   802-1x.private-key property. This is normally used by secret agents,
+     *   not directly by users.
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: private-key-password
      * variable: IEEE_8021X_PRIVATE_KEY_PASSWORD(+)
@@ -4203,6 +4259,13 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * Setting this property directly is discouraged; use the
      * nm_setting_802_1x_set_phase2_private_key() function instead.
      **/
+    /* ---nmcli---
+     * property: phase2-private-key
+     * description:
+     *   The path to the "phase 2" inner private key when the 802-1x.phase2-auth
+     *   or 802-1x.phase2-autheap property is set to "tls".
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: phase2-private-key
      * variable: IEEE_8021X_INNER_PRIVATE_KEY(+)
@@ -4228,6 +4291,14 @@ nm_setting_802_1x_class_init(NMSetting8021xClass *klass)
      * the private key by the nm_setting_802_1x_set_phase2_private_key()
      * function.
      **/
+    /* ---nmcli---
+     * property: phase2-private-key-password
+     * description:
+     *   The password used to decrypt the "phase 2" private key specified in the
+     *   802-1x.phase2-private-key property. This is normally used by secret agents,
+     *   not directly by users.
+     * ---end---
+     */
     /* ---ifcfg-rh---
      * property: phase2-private-key-password
      * variable: IEEE_8021X_INNER_PRIVATE_KEY_PASSWORD(+)
diff --git a/src/libnmc-setting/nm-meta-setting-desc.c b/src/libnmc-setting/nm-meta-setting-desc.c
index fd541faaea..da00c30b0c 100644
--- a/src/libnmc-setting/nm-meta-setting-desc.c
+++ b/src/libnmc-setting/nm-meta-setting-desc.c
@@ -4922,11 +4922,6 @@ static const NMMetaPropertyInfo *const property_infos_802_1X[] = {
         .property_type =                &_pt_gobject_string,
     ),
     PROPERTY_INFO_WITH_DESC (NM_SETTING_802_1X_CA_CERT,
-        .describe_message =
-            N_("Enter file path to CA certificate (optionally prefixed with file://).\n"
-               "  [file://]<file path>\n"
-               "Note that nmcli does not support specifying certificates as raw blob data.\n"
-               "Example: /home/cimrman/cacert.crt\n"),
         .property_type =                &_pt_cert_8021x,
         .property_typ_data = DEFINE_PROPERTY_TYP_DATA_SUBTYPE (cert_8021x,
             .scheme_type =              NM_SETTING_802_1X_SCHEME_TYPE_CA_CERT,
@@ -4965,11 +4960,6 @@ static const NMMetaPropertyInfo *const property_infos_802_1X[] = {
         .property_type =                &_pt_gobject_string,
     ),
     PROPERTY_INFO_WITH_DESC (NM_SETTING_802_1X_CLIENT_CERT,
-        .describe_message =
-            N_("Enter file path to client certificate (optionally prefixed with file://).\n"
-               "  [file://]<file path>\n"
-               "Note that nmcli does not support specifying certificates as raw blob data.\n"
-               "Example: /home/cimrman/jara.crt\n"),
         .property_type =                &_pt_cert_8021x,
         .property_typ_data = DEFINE_PROPERTY_TYP_DATA_SUBTYPE (cert_8021x,
             .scheme_type =              NM_SETTING_802_1X_SCHEME_TYPE_CLIENT_CERT,
@@ -5022,12 +5012,6 @@ static const NMMetaPropertyInfo *const property_infos_802_1X[] = {
         ),
     ),
     PROPERTY_INFO_WITH_DESC (NM_SETTING_802_1X_PHASE2_CA_CERT,
-        .describe_message =
-            N_("Enter file path to CA certificate for inner authentication (optionally prefixed\n"
-               "with file://).\n"
-               "  [file://]<file path>\n"
-               "Note that nmcli does not support specifying certificates as raw blob data.\n"
-               "Example: /home/cimrman/ca-zweite-phase.crt\n"),
         .property_type =                &_pt_cert_8021x,
         .property_typ_data = DEFINE_PROPERTY_TYP_DATA_SUBTYPE (cert_8021x,
             .scheme_type =              NM_SETTING_802_1X_SCHEME_TYPE_PHASE2_CA_CERT,
@@ -5070,12 +5054,6 @@ static const NMMetaPropertyInfo *const property_infos_802_1X[] = {
         .property_type =                &_pt_gobject_string,
     ),
     PROPERTY_INFO_WITH_DESC (NM_SETTING_802_1X_PHASE2_CLIENT_CERT,
-        .describe_message =
-            N_("Enter file path to client certificate for inner authentication (optionally prefixed\n"
-               "with file://).\n"
-               "  [file://]<file path>\n"
-               "Note that nmcli does not support specifying certificates as raw blob data.\n"
-               "Example: /home/cimrman/jara-zweite-phase.crt\n"),
         .property_type =                &_pt_cert_8021x,
         .property_typ_data = DEFINE_PROPERTY_TYP_DATA_SUBTYPE (cert_8021x,
             .scheme_type =              NM_SETTING_802_1X_SCHEME_TYPE_PHASE2_CLIENT_CERT,
@@ -5114,11 +5092,6 @@ static const NMMetaPropertyInfo *const property_infos_802_1X[] = {
         .property_type =                &_pt_gobject_secret_flags,
     ),
     PROPERTY_INFO_WITH_DESC (NM_SETTING_802_1X_PRIVATE_KEY,
-        .describe_message =
-            N_("Enter path to a private key and the key password (if not set yet):\n"
-               "  [file://]<file path> [<password>]\n"
-               "Note that nmcli does not support specifying private key as raw blob data.\n"
-               "Example: /home/cimrman/jara-priv-key Dardanely\n"),
         .property_type =                &_pt_cert_8021x,
         .property_typ_data = DEFINE_PROPERTY_TYP_DATA_SUBTYPE (cert_8021x,
             .scheme_type =              NM_SETTING_802_1X_SCHEME_TYPE_PRIVATE_KEY,
@@ -5132,11 +5105,6 @@ static const NMMetaPropertyInfo *const property_infos_802_1X[] = {
         .property_type =                &_pt_gobject_secret_flags,
     ),
     PROPERTY_INFO_WITH_DESC (NM_SETTING_802_1X_PHASE2_PRIVATE_KEY,
-        .describe_message =
-            N_("Enter path to a private key and the key password (if not set yet):\n"
-               "  [file://]<file path> [<password>]\n"
-               "Note that nmcli does not support specifying private key as raw blob data.\n"
-               "Example: /home/cimrman/jara-priv-key Dardanely\n"),
         .property_type =                &_pt_cert_8021x,
         .property_typ_data = DEFINE_PROPERTY_TYP_DATA_SUBTYPE (cert_8021x,
             .scheme_type =              NM_SETTING_802_1X_SCHEME_TYPE_PHASE2_PRIVATE_KEY,
diff --git a/src/libnmc-setting/settings-docs.h.in b/src/libnmc-setting/settings-docs.h.in
index 2a4e3991f2..fc5299fc4c 100644
--- a/src/libnmc-setting/settings-docs.h.in
+++ b/src/libnmc-setting/settings-docs.h.in
@@ -36,11 +36,11 @@
 #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\"; 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 N_("Contains the path to the CA certificate if used by the EAP method specified in the 802-1x.eap property. 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 802-1x.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. 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 N_("Contains the path to the client certificate if used by the EAP method specified in the 802-1x.eap property.")
 #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.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_DOMAIN_MATCH N_("Constraint for server domain name. If set, this list of FQDNs is used as a match requirement for dNSName element(s) of the certificate presented by the authentication server.  If a matching dNSName is found, this constraint is met.  If no dNSName values are present, this constraint is matched against SubjectName CN using the same comparison. Multiple valid FQDNs can be passed as a \";\" delimited list.")
@@ -61,23 +61,23 @@
 #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 authentication method when an EAP method that uses an inner TLS tunnel is specified in the \"eap\" property.  For TTLS this property selects one of the supported non-EAP inner methods: \"pap\", \"chap\", \"mschap\", \"mschapv2\" while \"phase2-autheap\" selects an EAP inner method.  For PEAP this selects an inner EAP method, one of: \"gtc\", \"otp\", \"md5\" and \"tls\". Each \"phase 2\" inner method requires specific parameters for successful authentication; see the wpa_supplicant documentation for more details. Both \"phase2-auth\" and \"phase2-autheap\" cannot be specified.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_AUTHEAP N_("Specifies the allowed \"phase 2\" inner EAP-based authentication method when TTLS 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\"; 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 N_("Contains the path to the \"phase 2\" CA certificate if used by the EAP method specified in the 802-1x.phase2-auth or 802-1x.phase2-autheap properties. 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 802-1x.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. 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 N_("Contains the path to the \"phase 2\" client certificate if used by the EAP method specified in the 802-1x.phase2-auth or 802-1x.phase2-autheap properties.")
 #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.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_DOMAIN_MATCH N_("Constraint for server domain name. If set, this list of FQDNs is used as a match requirement for dNSName element(s) of the certificate presented by the authentication server during the inner \"phase 2\" authentication. If a matching dNSName is found, this constraint is met.  If no dNSName values are present, this constraint is matched against SubjectName CN using the same comparison. Multiple valid FQDNs can be passed as a \";\" delimited list.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_DOMAIN_SUFFIX_MATCH N_("Constraint for server domain name. If set, this FQDN is used as a suffix match requirement for dNSName element(s) of the certificate presented by the authentication server during the inner \"phase 2\" authentication.  If a matching dNSName is found, this constraint is met.  If no dNSName values are present, this constraint is matched against SubjectName CN using same suffix match comparison. Since version 1.24, multiple valid FQDNs can be passed as a \";\" delimited list.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY N_("Contains the \"phase 2\" inner private key when the \"phase2-auth\" or \"phase2-autheap\" property is set to \"tls\". Key data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme and private keys, this property should be set to the key's encrypted PEM encoded data. When using private keys with the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte. When using PKCS#12 format private keys and the blob scheme, this property should be set to the PKCS#12 data and the \"phase2-private-key-password\" property must be set to password used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files and the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte, and as with the blob scheme the \"phase2-private-key-password\" property must be set to the password used to decode the PKCS#12 private key and certificate.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY_PASSWORD N_("The password used to decrypt the \"phase 2\" private key specified in the \"phase2-private-key\" property when the private key either uses the path scheme, or is a PKCS#12 format key.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY N_("The path to the \"phase 2\" inner private key when the 802-1x.phase2-auth or 802-1x.phase2-autheap property is set to \"tls\".")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY_PASSWORD N_("The password used to decrypt the \"phase 2\" private key specified in the 802-1x.phase2-private-key property. This is normally used by secret agents, not directly by users.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_PRIVATE_KEY_PASSWORD_FLAGS N_("Flags indicating how to handle the \"phase2-private-key-password\" property.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PHASE2_SUBJECT_MATCH N_("Substring to be matched against the subject of the certificate presented by the authentication server during the inner \"phase 2\" authentication. When unset, no verification of the authentication server certificate's subject is performed. This property provides little security, if any, and should not be used.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PIN N_("PIN used for EAP authentication methods.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PIN_FLAGS N_("Flags indicating how to handle the \"pin\" property.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY N_("Contains the private key when the \"eap\" property is set to \"tls\". Key data is specified using a \"scheme\"; two are currently supported: blob and path. When using the blob scheme and private keys, this property should be set to the key's encrypted PEM encoded data. When using private keys with the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte. When using PKCS#12 format private keys and the blob scheme, this property should be set to the PKCS#12 data and the \"private-key-password\" property must be set to password used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files and the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string \"file://\" and ending with a terminating NUL byte, and as with the blob scheme the \"private-key-password\" property must be set to the password used to decode the PKCS#12 private key and certificate. WARNING: \"private-key\" is not a \"secret\" property, and thus unencrypted private key data using the BLOB scheme may be readable by unprivileged users.  Private keys should always be encrypted with a private key password to prevent unauthorized access to unencrypted private key data.")
-#define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY_PASSWORD N_("The password used to decrypt the private key specified in the \"private-key\" property when the private key either uses the path scheme, or if the private key is a PKCS#12 format key.")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY N_("The path to the private key when the 802-1.eap property is set to \"tls\".")
+#define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY_PASSWORD N_("The password used to decrypt the private key specified in the 802-1x.private-key property. This is normally used by secret agents, not directly by users.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_PRIVATE_KEY_PASSWORD_FLAGS N_("Flags indicating how to handle the \"private-key-password\" property.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_SUBJECT_MATCH N_("Substring to be matched against the subject of the certificate presented by the authentication server. When unset, no verification of the authentication server certificate's subject is performed. This property provides little security, if any, and should not be used.")
 #define DESCRIBE_DOC_NM_SETTING_802_1X_SYSTEM_CA_CERTS N_("When TRUE, overrides the \"ca-path\" and \"phase2-ca-path\" properties using the system CA directory specified at configure time with the --system-ca-path switch.  The certificates in this directory are added to the verification chain in addition to any certificates specified by the \"ca-cert\" and \"phase2-ca-cert\" properties. If the path provided with --system-ca-path is rather a file name (bundle of trusted CA certificates), it overrides \"ca-cert\" and \"phase2-ca-cert\" properties instead (sets ca_cert/ca_cert2 options for wpa_supplicant).")
diff --git a/src/nmcli/gen-metadata-nm-settings-nmcli.xml.in b/src/nmcli/gen-metadata-nm-settings-nmcli.xml.in
index 24d1ddbf31..9008214dce 100644
--- a/src/nmcli/gen-metadata-nm-settings-nmcli.xml.in
+++ b/src/nmcli/gen-metadata-nm-settings-nmcli.xml.in
@@ -185,7 +185,7 @@
                   nmcli-description="UTF-8 encoded file path containing PAC for EAP-FAST."
                   format="string" />
         <property name="ca-cert"
-                  nmcli-description="Contains the CA certificate if used by the EAP method specified in the &quot;eap&quot; property. Certificate data is specified using a &quot;scheme&quot;; three are currently supported: blob, path and pkcs#11 URL. When using the blob scheme this property should be set to the certificate&apos;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 &quot;file://&quot; 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."
+                  nmcli-description="Contains the path to the CA certificate if used by the EAP method specified in the 802-1x.eap property. 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 802-1x.system-ca-certs will override this setting to use the built-in path, if the built-in path is not a directory."
                   format="filesystem path" />
         <property name="ca-cert-password"
                   nmcli-description="The password used to access the CA certificate stored in &quot;ca-cert&quot; property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login."
@@ -210,7 +210,7 @@
                   nmcli-description="Constraint for server domain name. If set, this list of FQDNs is used as a match requirement for dNSName element(s) of the certificate presented by the authentication server.  If a matching dNSName is found, this constraint is met.  If no dNSName values are present, this constraint is matched against SubjectName CN using the same comparison. Multiple valid FQDNs can be passed as a &quot;;&quot; delimited list."
                   format="string" />
         <property name="client-cert"
-                  nmcli-description="Contains the client certificate if used by the EAP method specified in the &quot;eap&quot; property. Certificate data is specified using a &quot;scheme&quot;; 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&apos;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 &quot;file://&quot; and ending with a terminating NUL byte."
+                  nmcli-description="Contains the path to the client certificate if used by the EAP method specified in the 802-1x.eap property."
                   format="filesystem path" />
         <property name="client-cert-password"
                   nmcli-description="The password used to access the client certificate stored in &quot;client-cert&quot; property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login."
@@ -244,7 +244,7 @@
                   format="string"
                   values="md5, mschapv2, otp, gtc, tls" />
         <property name="phase2-ca-cert"
-                  nmcli-description="Contains the &quot;phase 2&quot; CA certificate if used by the EAP method specified in the &quot;phase2-auth&quot; or &quot;phase2-autheap&quot; properties. Certificate data is specified using a &quot;scheme&quot;; three are currently supported: blob, path and pkcs#11 URL. When using the blob scheme this property should be set to the certificate&apos;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 &quot;file://&quot; 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."
+                  nmcli-description="Contains the path to the &quot;phase 2&quot; CA certificate if used by the EAP method specified in the 802-1x.phase2-auth or 802-1x.phase2-autheap properties. 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 802-1x.system-ca-certs will override this setting to use the built-in path, if the built-in path is not a directory."
                   format="filesystem path" />
         <property name="phase2-ca-cert-password"
                   nmcli-description="The password used to access the &quot;phase2&quot; CA certificate stored in &quot;phase2-ca-cert&quot; property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login."
@@ -269,7 +269,7 @@
                   nmcli-description="Constraint for server domain name. If set, this list of FQDNs is used as a match requirement for dNSName element(s) of the certificate presented by the authentication server during the inner &quot;phase 2&quot; authentication. If a matching dNSName is found, this constraint is met.  If no dNSName values are present, this constraint is matched against SubjectName CN using the same comparison. Multiple valid FQDNs can be passed as a &quot;;&quot; delimited list."
                   format="string" />
         <property name="phase2-client-cert"
-                  nmcli-description="Contains the &quot;phase 2&quot; client certificate if used by the EAP method specified in the &quot;phase2-auth&quot; or &quot;phase2-autheap&quot; properties. Certificate data is specified using a &quot;scheme&quot;; 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&apos;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 &quot;file://&quot; 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."
+                  nmcli-description="Contains the path to the &quot;phase 2&quot; client certificate if used by the EAP method specified in the 802-1x.phase2-auth or 802-1x.phase2-autheap properties."
                   format="filesystem path" />
         <property name="phase2-client-cert-password"
                   nmcli-description="The password used to access the &quot;phase2&quot; client certificate stored in &quot;phase2-client-cert&quot; property. Only makes sense if the certificate is stored on a PKCS#11 token that requires a login."
@@ -293,20 +293,20 @@
                   format="flags (NMSettingSecretFlags)"
                   values="none (0x0), agent-owned (0x1), not-saved (0x2), not-required (0x4)" />
         <property name="private-key"
-                  nmcli-description="Contains the private key when the &quot;eap&quot; property is set to &quot;tls&quot;. Key data is specified using a &quot;scheme&quot;; two are currently supported: blob and path. When using the blob scheme and private keys, this property should be set to the key&apos;s encrypted PEM encoded data. When using private keys with the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string &quot;file://&quot; and ending with a terminating NUL byte. When using PKCS#12 format private keys and the blob scheme, this property should be set to the PKCS#12 data and the &quot;private-key-password&quot; property must be set to password used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files and the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string &quot;file://&quot; and ending with a terminating NUL byte, and as with the blob scheme the &quot;private-key-password&quot; property must be set to the password used to decode the PKCS#12 private key and certificate. WARNING: &quot;private-key&quot; is not a &quot;secret&quot; property, and thus unencrypted private key data using the BLOB scheme may be readable by unprivileged users.  Private keys should always be encrypted with a private key password to prevent unauthorized access to unencrypted private key data."
+                  nmcli-description="The path to the private key when the 802-1.eap property is set to &quot;tls&quot;."
                   format="filesystem path" />
         <property name="private-key-password"
-                  nmcli-description="The password used to decrypt the private key specified in the &quot;private-key&quot; property when the private key either uses the path scheme, or if the private key is a PKCS#12 format key."
+                  nmcli-description="The password used to decrypt the private key specified in the 802-1x.private-key property. This is normally used by secret agents, not directly by users."
                   format="string" />
         <property name="private-key-password-flags"
                   nmcli-description="Flags indicating how to handle the &quot;private-key-password&quot; property."
                   format="flags (NMSettingSecretFlags)"
                   values="none (0x0), agent-owned (0x1), not-saved (0x2), not-required (0x4)" />
         <property name="phase2-private-key"
-                  nmcli-description="Contains the &quot;phase 2&quot; inner private key when the &quot;phase2-auth&quot; or &quot;phase2-autheap&quot; property is set to &quot;tls&quot;. Key data is specified using a &quot;scheme&quot;; two are currently supported: blob and path. When using the blob scheme and private keys, this property should be set to the key&apos;s encrypted PEM encoded data. When using private keys with the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string &quot;file://&quot; and ending with a terminating NUL byte. When using PKCS#12 format private keys and the blob scheme, this property should be set to the PKCS#12 data and the &quot;phase2-private-key-password&quot; property must be set to password used to decrypt the PKCS#12 certificate and key. When using PKCS#12 files and the path scheme, this property should be set to the full UTF-8 encoded path of the key, prefixed with the string &quot;file://&quot; and ending with a terminating NUL byte, and as with the blob scheme the &quot;phase2-private-key-password&quot; property must be set to the password used to decode the PKCS#12 private key and certificate."
+                  nmcli-description="The path to the &quot;phase 2&quot; inner private key when the 802-1x.phase2-auth or 802-1x.phase2-autheap property is set to &quot;tls&quot;."
                   format="filesystem path" />
         <property name="phase2-private-key-password"
-                  nmcli-description="The password used to decrypt the &quot;phase 2&quot; private key specified in the &quot;phase2-private-key&quot; property when the private key either uses the path scheme, or is a PKCS#12 format key."
+                  nmcli-description="The password used to decrypt the &quot;phase 2&quot; private key specified in the 802-1x.phase2-private-key property. This is normally used by secret agents, not directly by users."
                   format="string" />
         <property name="phase2-private-key-password-flags"
                   nmcli-description="Flags indicating how to handle the &quot;phase2-private-key-password&quot; property."