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/CHANGELOG.rst b/CHANGELOG.rst
index a4441b8..d029ce6 100644
--- a/CHANGELOG.rst
+++ b/CHANGELOG.rst
@@ -14,27 +14,21 @@
* **BACKWARDS INCOMPATIBLE:** ``Whirlpool``, ``RIPEMD160``, and
``UnsupportedExtension`` have been removed in accordance with our
:doc:`/api-stability` policy.
+* **BACKWARDS INCOMPATIBLE:** :attr:`~cryptography.x509.DNSName.value`,
+ :attr:`~cryptography.x509.RFC822Name.value`, and
+ :attr:`~cryptography.x509.UniformResourceIdentifier.value` will now return
+ an :term:`A-label` string when parsing a certificate containing an
+ internationalized domain name (IDN) or if the caller passed a :term:`U-label`
+ to the constructor. See below for additional deprecations related to this
+ change.
* Installing ``cryptography`` now requires ``pip`` 6 or newer.
-* Deprecated passing unicode to the :class:`~cryptography.x509.DNSName`
- constructor. Instead, users should pass DNS names as ``bytes``, with ``idna``
- encoding if necessary. In addition, the
- :attr:`~cryptography.x509.DNSName.value` attribute was deprecated, users
- should use :attr:`~cryptography.x509.DNSName.bytes_value` to access the
- raw DNS name.
-* Deprecated passing unicode to the
- :class:`~cryptography.x509.UniformResourceIdentifier` constructor. Instead,
- users should pass URIs as ``bytes``, with ``idna`` encoding if
- necessary. In addition, the
- :attr:`~cryptography.x509.UniformResourceIdentifier.value` attribute was
- deprecated, users should use
- :attr:`~cryptography.x509.UniformResourceIdentifier.bytes_value` to access
- the raw value.
-* Deprecated passing unicode to the :class:`~cryptography.x509.RFC822Name`
- constructor. Instead, users should pass email addresses as ``bytes``, with
- ``idna`` encoding of the hostname if necessary. In addition, the
- :attr:`~cryptography.x509.RFC822Name.value` attribute was deprecated, users
- should use :attr:`~cryptography.x509.RFC822Name.bytes_value` to access the
- raw value.
+* Deprecated passing :term:`U-label` strings to the
+ :class:`~cryptography.x509.DNSName`,
+ :class:`~cryptography.x509.UniformResourceIdentifier`, and
+ :class:`~cryptography.x509.RFC822Name` constructors. Instead, users should
+ pass values as :term:`A-label` strings with ``idna`` encoding if necessary.
+ This change will not affect anyone who is not processing internationalized
+ domains.
* Added support for
:class:`~cryptography.hazmat.primitives.ciphers.algorithms.ChaCha20`. In
most cases users should choose
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)