doc: added section about subject alternative names

3 files changed, 35 insertions, 1 deletions

diff --git a/doc/cha-bib.texi b/doc/cha-bib.texi
index 1dc8ff204d..1867d0c563 100644
--- a/doc/cha-bib.texi
+++ b/doc/cha-bib.texi
@@ -26,6 +26,11 @@ NIST Special Publication 800-57, "Recommendation for Key Management -
 Part 1: General (Revised)", March 2007, available from
 @url{http://csrc.nist.gov/publications/nistpubs/800-57/sp800-57-Part1-revised2_Mar08-2007.pdf}.
 
+@item @anchor{RFC6125}[RFC6125]
+Peter Saint-Andre and Jeff Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)",
+March 2011, Available from
+@url{http://www.ietf.org/rfc/rfc6125.txt}.
+
 @item @anchor{RFC2246}[RFC2246]
 Tim Dierks and Christopher Allen, "The TLS Protocol Version 1.0",
 January 1999, Available from
diff --git a/doc/cha-cert-auth.texi b/doc/cha-cert-auth.texi
index 10a74776b7..70ba35b143 100644
--- a/doc/cha-cert-auth.texi
+++ b/doc/cha-cert-auth.texi
@@ -80,6 +80,7 @@ acceptable.  The framework is illustrated on @ref{fig-x509}.
 @menu
 * X.509 certificate structure::
 * Importing an X.509 certificate::
+* X.509 certificate names::
 * X.509 distinguished names::
 * X.509 extensions::
 * X.509 public and private keys::
@@ -166,6 +167,25 @@ In all cases after use a certificate must be deinitialized using @funcref{gnutls
 Note that although the functions above apply to @code{gnutls_x509_crt_t} structure, similar functions
 exist for the CRL structure @code{gnutls_x509_crl_t}.
 
+@node X.509 certificate names
+@subsubsection X.509 certificate names
+@cindex X.509 certificate name
+
+X.509 certificates allow for multiple names and types of names to be specified.
+CA certificates often rely on X.509 distinguished names (see @ref{X.509 distinguished names})
+for unique identification, while end-user and server certificates rely on the
+'subject alternative names'. The subject alternative names provide a typed name, e.g.,
+a DNS name, or an email address, which identifies the owner of the certificate.
+The following functions provide access to that names.
+
+@showfuncB{gnutls_x509_crt_get_subject_alt_name2,gnutls_x509_crt_set_subject_alt_name}
+@showfuncC{gnutls_subject_alt_names_init,gnutls_subject_alt_names_get,gnutls_subject_alt_names_set}
+
+Note however, that server certificates often used the Common Name (CN), part of the
+certificate DistinguishedName to place a single DNS address. That practice is discouraged
+(see @xcite{RFC6125}), because only a single address can be specified, and the CN field is
+free-form making matching ambiguous.
+
 @node X.509 distinguished names
 @subsubsection X.509 distinguished names
 @cindex X.509 distinguished name
diff --git a/doc/latex/gnutls.bib b/doc/latex/gnutls.bib
index 5989fe6a77..5eed770865 100644
--- a/doc/latex/gnutls.bib
+++ b/doc/latex/gnutls.bib
@@ -26,7 +26,16 @@
 	month = "May",
 	year = "2010",
 	note = "Available from \url{http://www.ietf.org/rfc/rfc5764}",
-	url = "http://www.ietf.org/rfc/rfc5764 "
+	url = "http://www.ietf.org/rfc/rfc5764"
+}
+
+@Misc{ RFC6125,
+	author = "Peter Saint-Andre and Jeff Hodges",
+	title = "{Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)}",
+	month = "March",
+	year = "2011",
+	note = "Available from \url{http://www.ietf.org/rfc/rfc6125}",
+	url = "http://www.ietf.org/rfc/rfc6125"
 }
 
 @Misc{ RFC2246 ,