Improve subject_match and domain_suffix_match documentation

These were already covered in both README-HS20 for credentials and in
header files for developers' documentation, but the copy in
wpa_supplicant.conf did not include all the details. In addition, add a
clearer note pointing at subject_match not being suitable for suffix
matching domain names; domain_suffix_match must be used for that.

Signed-off-by: Jouni Malinen <j@w1.fi>

diff --git a/src/eap_peer/eap_config.h b/src/eap_peer/eap_config.h
index 3584bdb..4eb5b95 100644 (file)
--- a/src/eap_peer/eap_config.h
+++ b/src/eap_peer/eap_config.h
@@ -186,6 +186,10 @@ struct eap_peer_config {
         * string is in following format:
         *
         * /C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@n.example.com
+        *
+        * Note: Since this is a substring match, this cannot be used securily
+        * to do a suffix match against a possible domain name in the CN entry.
+        * For such a use case, domain_suffix_match should be used instead.
         */
        u8 *subject_match;
 

diff --git a/wpa_supplicant/wpa_supplicant.conf b/wpa_supplicant/wpa_supplicant.conf
index cf5230a..7d189c7 100644 (file)
--- a/wpa_supplicant/wpa_supplicant.conf
+++ b/wpa_supplicant/wpa_supplicant.conf
@@ -865,6 +865,9 @@ fast_reauth=1
 #      sertificate is only accepted if it contains this string in the subject.
 #      The subject string is in following format:
 #      /C=US/ST=CA/L=San Francisco/CN=Test AS/emailAddress=as@example.com
+#      Note: Since this is a substring match, this cannot be used securily to
+#      do a suffix match against a possible domain name in the CN entry. For
+#      such a use case, domain_suffix_match should be used instead.
 # altsubject_match: Semicolon separated string of entries to be matched against
 #      the alternative subject name of the authentication server certificate.
 #      If this string is set, the server sertificate is only accepted if it
@@ -873,6 +876,20 @@ fast_reauth=1
 #      Example: EMAIL:server@example.com
 #      Example: DNS:server.example.com;DNS:server2.example.com
 #      Following types are supported: EMAIL, DNS, URI
+# domain_suffix_match: Constraint for server domain name. If set, this FQDN is
+#      used as a suffix match requirement for the AAAserver certificate in
+#      SubjectAltName dNSName element(s). 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.
+#
+#      Suffix match here means that the host/domain name is compared one label
+#      at a time starting from the top-level domain and all the labels in
+#      domain_suffix_match shall be included in the certificate. The
+#      certificate may include additional sub-level labels in addition to the
+#      required labels.
+#
+#      For example, domain_suffix_match=example.com would match
+#      test.example.com but would not match test-example.com.
 # phase1: Phase1 (outer authentication, i.e., TLS tunnel) parameters
 #      (string with field-value pairs, e.g., "peapver=0" or
 #      "peapver=1 peaplabel=1")
@@ -939,9 +956,12 @@ fast_reauth=1
 # private_key2_passwd: Password for private key file
 # dh_file2: File path to DH/DSA parameters file (in PEM format)
 # subject_match2: Substring to be matched against the subject of the
-#      authentication server certificate.
-# altsubject_match2: Substring to be matched against the alternative subject
-#      name of the authentication server certificate.
+#      authentication server certificate. See subject_match for more details.
+# altsubject_match2: Semicolon separated string of entries to be matched
+#      against the alternative subject name of the authentication server
+#      certificate. See altsubject_match documentation for more details.
+# domain_suffix_match2: Constraint for server domain name. See
+#      domain_suffix_match for more details.
 #
 # fragment_size: Maximum EAP fragment size in bytes (default 1398).
 #      This value limits the fragment size for EAP methods that support