From 01ee6f5e391eee76e6cd3062de8fc84851bd06e3 Mon Sep 17 00:00:00 2001
From: Fraser Tweedale <frase@frase.id.au>
Date: Sat, 12 Nov 2016 01:28:56 +1000
Subject: Name: add support for multi-value RDNs (#3202)

Update the Name class to accept and internally store a list of
RelativeDistinguishedName objects.  Add the 'rdns' attribute to give
access to the RDNs.  Update ASN.1 routines to correctly decode and
encode multi-value RDNs.

Fixes: https://github.com/pyca/cryptography/issues/3199
---
 docs/x509/reference.rst | 21 ++++++++++++++++++++-
 1 file changed, 20 insertions(+), 1 deletion(-)

(limited to 'docs/x509')

diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
index c5623315..ce479a7c 100644
--- a/docs/x509/reference.rst
+++ b/docs/x509/reference.rst
@@ -1102,6 +1102,18 @@ X.509 CSR (Certificate Signing Request) Builder Object
     slash or comma delimited string (e.g. ``/CN=mydomain.com/O=My Org/C=US`` or
     ``CN=mydomain.com, O=My Org, C=US``).
 
+    Technically, a Name is a list of *sets* of attributes, called *Relative
+    Distinguished Names* or *RDNs*, although multi-valued RDNs are rarely
+    encountered.  The iteration order of values within a multi-valued RDN is
+    undefined.  If you need to handle multi-valued RDNs, the ``rdns`` property
+    gives access to an ordered list of :class:`RelativeDistinguishedName`
+    objects.
+
+    A Name can be initialized with an iterable of :class:`NameAttribute` (the
+    common case where each RDN has a single attribute) or an iterable of
+    :class:`RelativeDistinguishedName` objects (in the rare case of
+    multi-valued RDNs).
+
     .. doctest::
 
         >>> len(cert.subject)
@@ -1112,6 +1124,12 @@ X.509 CSR (Certificate Signing Request) Builder Object
         <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.10, name=organizationName)>, value=u'Test Certificates 2011')>
         <NameAttribute(oid=<ObjectIdentifier(oid=2.5.4.3, name=commonName)>, value=u'Good CA')>
 
+    .. attribute:: rdns
+
+        .. versionadded:: 1.6
+
+        :type: list of :class:`RelativeDistinguishedName`
+
     .. method:: get_attributes_for_oid(oid)
 
         :param oid: An :class:`ObjectIdentifier` instance.
@@ -1142,7 +1160,8 @@ X.509 CSR (Certificate Signing Request) Builder Object
 
     .. versionadded:: 0.8
 
-    An X.509 name consists of a list of NameAttribute instances.
+    An X.509 name consists of a list of :class:`RelativeDistinguishedName`
+    instances, which consist of a set of :class:`NameAttribute` instances.
 
     .. attribute:: oid
 
-- 
cgit v1.2.3