docs for what bytes means for DNSName, URI, and RFC822Name (#3904)
diff --git a/docs/glossary.rst b/docs/glossary.rst
index a630878..3a1280a 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -79,5 +79,11 @@
but does not allow access to the key itself. Typically an opaque key is
loaded from a `hardware security module`_ (HSM).
+ A-label
+ The ASCII compatible encoded (ACE) representation of an
+ internationalized (unicode) domain name. A-labels begin with the
+ prefix ``xn--``. To create an A-label from a unicode domain string use
+ a library like `idna`_.
.. _`hardware security module`: https://en.wikipedia.org/wiki/Hardware_security_module
+.. _`idna`: https://pypi.org/project/idna/
diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
index 2e86cb1..71ac9d9 100644
--- a/docs/x509/reference.rst
+++ b/docs/x509/reference.rst
@@ -1242,13 +1242,18 @@
.. versionadded:: 0.9
- This corresponds to an email address. For example, ``user@example.com``.
-
..note::
Starting with version 2.1 unicode input is deprecated. If passing an
- internationalized domain name (IDN) you should first IDNA encode the
- hostname and then pass the resulting bytes.
+ email address containing an internationalized domain name (IDN) you
+ should first IDNA encode the hostname and then pass the resulting
+ bytes.
+
+ This corresponds to an email address. For example, ``user@example.com``.
+
+ :param bytes value: The email address. If the address contains an
+ internationalized domain name then it must be encoded to an
+ :term:`A-label` before being passed.
.. attribute:: bytes_value
@@ -1256,6 +1261,9 @@
:type: bytes
+ The value as a byte string. This will contain an :term:`A-label` if
+ the domain in the address is an internationalized domain name.
+
.. attribute:: value
.. deprecated:: 2.1
@@ -1268,14 +1276,26 @@
.. versionadded:: 0.9
+ ..note::
+
+ Starting with version 2.1 unicode input is deprecated. If passing an
+ internationalized domain name (IDN) you should first IDNA encode the
+ hostname and then pass the resulting bytes.
+
This corresponds to a domain name. For example, ``cryptography.io``.
+ :param bytes value: The domain name. If it is an internationalized domain
+ name then it must be encoded to an :term:`A-label` before being passed.
+
.. attribute:: bytes_value
.. versionadded:: 2.1
:type: bytes
+ The value as a byte string. This will contain an :term:`A-label` if
+ it is an internationalized domain name.
+
.. attribute:: value
.. deprecated:: 2.1
@@ -1298,14 +1318,17 @@
.. versionadded:: 0.9
- This corresponds to a uniform resource identifier. For example,
- ``https://cryptography.io``.
-
..note::
Starting with version 2.1 unicode input is deprecated. If passing an
- internationalized domain name (IDN) you should first IDNA encode the
- hostname and then pass the resulting bytes.
+ internationalized domain name (IDN) within the URI you should first
+ IDNA encode the hostname and then pass the resulting bytes.
+
+ This corresponds to a uniform resource identifier. For example,
+ ``https://cryptography.io``.
+
+ :param bytes value: The URI. If it contains an internationalized domain
+ name then it must be encoded to an :term:`A-label` before being passed.
.. attribute:: bytes_value
@@ -1313,6 +1336,9 @@
:type: bytes
+ The value as a byte string. This will contain an :term:`A-label` if
+ the URI contains an internationalized domain name.
+
.. attribute:: value
.. deprecated:: 2.1