diff options
| author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2017-09-20 23:42:34 +0800 |
|---|---|---|
| committer | Alex Gaynor <alex.gaynor@gmail.com> | 2017-09-20 11:42:34 -0400 |
| commit | 1b86dc527dfecf1795ac28cd6bd32e8cf8725566 (patch) | |
| tree | 44b8a3cdbb465a8076bbe26458c5df60d075f045 /docs | |
| parent | d02842b03bf94e9f62e788a2120f02d96a2b0cfd (diff) | |
| download | cryptography-1b86dc527dfecf1795ac28cd6bd32e8cf8725566.tar.gz cryptography-1b86dc527dfecf1795ac28cd6bd32e8cf8725566.tar.bz2 cryptography-1b86dc527dfecf1795ac28cd6bd32e8cf8725566.zip | |
docs for what bytes means for DNSName, URI, and RFC822Name (#3904)
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/glossary.rst | 6 | ||||
| -rw-r--r-- | docs/x509/reference.rst | 44 |
2 files changed, 41 insertions, 9 deletions
diff --git a/docs/glossary.rst b/docs/glossary.rst index a630878c..3a1280a6 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -79,5 +79,11 @@ Glossary 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 2e86cb13..71ac9d99 100644 --- a/docs/x509/reference.rst +++ b/docs/x509/reference.rst @@ -1242,13 +1242,18 @@ General Name Classes .. 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 @@ General Name Classes :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 @@ General Name Classes .. 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 @@ General Name Classes .. 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 @@ General Name Classes :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 |