diff options
| -rw-r--r-- | CHANGELOG.rst | 34 | ||||
| -rw-r--r-- | docs/glossary.rst | 5 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 2 | ||||
| -rw-r--r-- | docs/x509/reference.rst | 94 |
4 files changed, 58 insertions, 77 deletions
diff --git a/CHANGELOG.rst b/CHANGELOG.rst index a4441b85..d029ce6f 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -14,27 +14,21 @@ Changelog * **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 df327605..ce08dbaa 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -94,5 +94,10 @@ Glossary 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 f0cfc88e..c53cc80f 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -24,6 +24,7 @@ decrypt Decrypts decrypted decrypting +deprecations DER deserialize deserialized @@ -74,6 +75,7 @@ plaintext pre preprocessor preprocessors +presentational pseudorandom pyOpenSSL relicensed diff --git a/docs/x509/reference.rst b/docs/x509/reference.rst index 238a24e5..014d1f47 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -1242,66 +1242,53 @@ General Name Classes .. 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:: - 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. + 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. - .. attribute:: bytes_value - .. versionadded:: 2.1 - - :type: bytes + This corresponds to an email address. For example, ``user@example.com``. - The value as a byte string. This will contain an :term:`A-label` if - the domain in the address is an internationalized domain name. + :param value: The email address. If the address 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:: 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:: - This corresponds to a domain name. For example, ``cryptography.io``. + 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. - :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 + This corresponds to a domain name. For example, ``cryptography.io``. - :type: bytes + :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. - 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 @@ General Name Classes .. versionadded:: 0.9 - ..note:: + .. versionchanged:: 2.1 + + .. warning:: - 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. + 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) |