Update docs and changelog for URI, RFC822Name, and DNSName (#3955)
* Update docs and changelog for URI, RFC822Name, and DNSName
As of 2.1 we want users to pass A-label strings, but we still accept
U-label strings and auto-encode on their behalf (with a deprecation
warning). However, we do not return U-label in the value attribute so
we are making a backwards incompatible change for users that utilize
internationalized domain names.
* language updates
* add presentational to the word list
* the linux dictionary is pathetic
diff --git a/docs/glossary.rst b/docs/glossary.rst
index df32760..ce08dba 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -94,5 +94,10 @@
bit key, you can calculate the number of bytes by dividing by 8. 128
divided by 8 is 16, so a 128 bit key is a 16 byte key.
+ U-label
+ The presentational unicode form of an internationalized domain
+ name. U-labels use unicode characters outside the ASCII range and
+ are encoded as A-labels when stored in certificates.
+
.. _`hardware security module`: https://en.wikipedia.org/wiki/Hardware_security_module
.. _`idna`: https://pypi.org/project/idna/
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index f0cfc88..c53cc80 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -24,6 +24,7 @@
Decrypts
decrypted
decrypting
+deprecations
DER
deserialize
deserialized
@@ -74,6 +75,7 @@
pre
preprocessor
preprocessors
+presentational
pseudorandom
pyOpenSSL
relicensed
diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst
index 238a24e..014d1f4 100644
--- a/docs/x509/reference.rst
+++ b/docs/x509/reference.rst
@@ -1242,66 +1242,53 @@
.. versionadded:: 0.9
- ..note::
+ .. versionchanged:: 2.1
- Starting with version 2.1 unicode input is deprecated. If passing an
- email address containing an internationalized domain name (IDN) you
- should first IDNA encode the hostname and then pass the resulting
- bytes.
+ .. warning::
+
+ Starting with version 2.1 :term:`U-label` input is deprecated. If
+ passing an internationalized domain name (IDN) you should first IDNA
+ encode the value and then pass the result as a string. Accessing
+ ``value`` will return the :term:`A-label` encoded form even if you pass
+ a U-label. This breaks backwards compatibility, but only for
+ internationalized domain names.
+
This corresponds to an email address. For example, ``user@example.com``.
- :param bytes value: The email address. If the address contains an
+ :param 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
-
- .. versionadded:: 2.1
-
- :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.
+ :term:`A-label` string before being passed.
.. attribute:: value
- .. deprecated:: 2.1
-
- Deprecated accessor for the idna-decoded value of :attr:`bytes_value`
-
:type: :term:`text`
.. class:: DNSName(value)
.. versionadded:: 0.9
- ..note::
+ .. versionchanged:: 2.1
- 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.
+ .. warning::
+
+ Starting with version 2.1 :term:`U-label` input is deprecated. If
+ passing an internationalized domain name (IDN) you should first IDNA
+ encode the value and then pass the result as a string. Accessing
+ ``value`` will return the :term:`A-label` encoded form even if you pass
+ a U-label. This breaks backwards compatibility, but only for
+ internationalized domain names.
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.
+ :param value: The domain name. If it is an internationalized domain
+ name then it must be encoded to an :term:`A-label` string 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.
+ :type: :term:`text`
.. attribute:: value
- .. deprecated:: 2.1
-
- Deprecated accessor for the idna-decoded value of :attr:`bytes_value`
-
:type: :term:`text`
.. class:: DirectoryName(value)
@@ -1318,33 +1305,26 @@
.. versionadded:: 0.9
- ..note::
+ .. versionchanged:: 2.1
- Starting with version 2.1 unicode input is deprecated. If passing an
- internationalized domain name (IDN) within the URI you should first
- IDNA encode the hostname and then pass the resulting bytes.
+ .. warning::
+
+ Starting with version 2.1 :term:`U-label` input is deprecated. If
+ passing an internationalized domain name (IDN) you should first IDNA
+ encode the value and then pass the result as a string. Accessing
+ ``value`` will return the :term:`A-label` encoded form even if you pass
+ a U-label. This breaks backwards compatibility, but only for
+ internationalized domain names.
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
-
- .. versionadded:: 2.1
-
- :type: bytes
-
- The value as a byte string. This will contain an :term:`A-label` if
- the URI contains an internationalized domain name.
+ :param value: The URI. If it contains an internationalized domain
+ name then it must be encoded to an :term:`A-label` string before
+ being passed.
.. attribute:: value
- .. deprecated:: 2.1
-
- Deprecated accessor for the idna-decoded value of :attr:`bytes_value`
-
:type: :term:`text`
.. class:: IPAddress(value)