let's talk about bits baby (#3956)

8 files changed, 71 insertions, 57 deletions

diff --git a/docs/glossary.rst b/docs/glossary.rst
index 3a1280a6..df327605 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -85,5 +85,14 @@ Glossary
         prefix ``xn--``. To create an A-label from a unicode domain string use
         a library like `idna`_.
 
+    bits
+        A bit is binary value -- a value that has only two possible states.
+        Typically binary values are represented visually as 0 or 1, but
+        remember that their actual value is not a printable character. A byte
+        on modern computers is 8 bits and represents 256 possible values. In
+        cryptographic applications when you see something say it requires a 128
+        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.
+
 .. _`hardware security module`: https://en.wikipedia.org/wiki/Hardware_security_module
 .. _`idna`: https://pypi.org/project/idna/
diff --git a/docs/hazmat/primitives/aead.rst b/docs/hazmat/primitives/aead.rst
index 3c45b523..7b01f745 100644
--- a/docs/hazmat/primitives/aead.rst
+++ b/docs/hazmat/primitives/aead.rst
@@ -122,7 +122,7 @@ also support providing integrity for associated data which is not encrypted.
         passed directly to the ``decrypt`` method.
 
         :param bytes nonce: NIST `recommends a 96-bit IV length`_ for best
-            performance but it can be up to 2\ :sup:`64` - 1 bits.
+            performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
             **NEVER REUSE A NONCE** with a key.
         :param bytes data: The data to encrypt.
         :param bytes associated_data: Additional data that should be
@@ -136,7 +136,7 @@ also support providing integrity for associated data which is not encrypted.
         ``associated_data`` in decrypt or the integrity check will fail.
 
         :param bytes nonce: NIST `recommends a 96-bit IV length`_ for best
-            performance but it can be up to 2\ :sup:`64` - 1 bits.
+            performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
             **NEVER REUSE A NONCE** with a key.
         :param bytes data: The data to decrypt (with tag appended).
         :param bytes associated_data: Additional data to authenticate. Can be
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 57b4a960..9da7273e 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -17,8 +17,8 @@ Generation
     Generate a DSA private key from the given key size. This function will
     generate a new set of parameters and key in one step.
 
-    :param int key_size: The length of the modulus in bits. It should be
-        either 1024, 2048 or 3072. For keys generated in 2015 this should
+    :param int key_size: The length of the modulus in :term:`bits`. It should
+        be either 1024, 2048 or 3072. For keys generated in 2015 this should
         be `at least 2048`_ (See page 41).  Note that some applications
         (such as SSH) have not yet gained support for larger key sizes
         specified in FIPS 186-3 and are still restricted to only the
diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst
index 50c38e3e..0bb74c6f 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -268,7 +268,7 @@ is faster than diffie-hellman`_.
 
 .. note::
     Curves with a size of `less than 224 bits`_ should not be used. You should
-    strongly consider using curves of at least 224 bits.
+    strongly consider using curves of at least 224 :term:`bits`.
 
 Generally the NIST prime field ("P") curves are significantly faster than the
 other types suggested by NIST at both signing and verifying with ECDSA.
@@ -415,8 +415,8 @@ Key Interfaces
 
         :type: int
 
-        Size (in bits) of a secret scalar for the curve (as generated by
-        :func:`generate_private_key`).
+        Size (in :term:`bits`) of a secret scalar for the curve (as generated
+        by :func:`generate_private_key`).
 
 
 .. class:: EllipticCurveSignatureAlgorithm
@@ -490,8 +490,8 @@ Key Interfaces
 
         :type: int
 
-        Size (in bits) of a secret scalar for the curve (as generated by
-        :func:`generate_private_key`).
+        Size (in :term:`bits`) of a secret scalar for the curve (as generated
+        by :func:`generate_private_key`).
 
 
 .. class:: EllipticCurvePrivateKeyWithSerialization
@@ -593,8 +593,8 @@ Key Interfaces
 
         :type: int
 
-        Size (in bits) of a secret scalar for the curve (as generated by
-        :func:`generate_private_key`).
+        Size (in :term:`bits`) of a secret scalar for the curve (as generated
+        by :func:`generate_private_key`).
 
 
 .. class:: EllipticCurvePublicKeyWithSerialization
diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst
index a49b4d34..607cebb1 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -19,9 +19,9 @@ mathematical properties`_.
     .. versionadded:: 0.5
 
     Generates a new RSA private key using the provided ``backend``.
-    ``key_size`` describes how many bits long the key should be, larger keys
-    provide more security, currently ``1024`` and below are considered
-    breakable, and ``2048`` or ``4096`` are reasonable default key sizes for
+    ``key_size`` describes how many :term:`bits` long the key should be. Larger
+    keys provide more security; currently ``1024`` and below are considered
+    breakable while ``2048`` or ``4096`` are reasonable default key sizes for
     new keys. The ``public_exponent`` indicates what one mathematical property
     of the key generation will be. Unless you have a specific reason to do
     otherwise, you should always `use 65537`_.
@@ -40,7 +40,7 @@ mathematical properties`_.
         Usually one of the small Fermat primes 3, 5, 17, 257, 65537. If in
         doubt you should `use 65537`_.
 
-    :param int key_size: The length of the modulus in bits. For keys
+    :param int key_size: The length of the modulus in :term:`bits`. For keys
         generated in 2015 it is strongly recommended to be
         `at least 2048`_ (See page 41). It must not be less than 512.
         Some backends may have additional limitations.
diff --git a/docs/hazmat/primitives/padding.rst b/docs/hazmat/primitives/padding.rst
index 45bcc139..e49fc494 100644
--- a/docs/hazmat/primitives/padding.rst
+++ b/docs/hazmat/primitives/padding.rst
@@ -36,8 +36,8 @@ multiple of the block size.
         >>> data + unpadder.finalize()
         '11111111111111112222222222'
 
-    :param block_size: The size of the block in bits that the data is being
-                       padded to.
+    :param block_size: The size of the block in :term:`bits` that the data is
+        being padded to.
     :raises ValueError: Raised if block size is not a multiple of 8 or is not
         between 0 and 2040 inclusive.
 
@@ -79,8 +79,8 @@ multiple of the block size.
         >>> data + unpadder.finalize()
         '11111111111111112222222222'
 
-    :param block_size: The size of the block in bits that the data is being
-        padded to.
+    :param block_size: The size of the block in :term:`bits` that the data is
+        being padded to.
     :raises ValueError: Raised if block size is not a multiple of 8 or is not
         between 0 and 2040 inclusive.
 
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 2635e753..aa577f07 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -93,7 +93,7 @@ Algorithms
     choice for encryption.
 
     :param bytes key: The secret key. This must be kept secret. Either ``128``,
-        ``192``, or ``256`` bits long.
+        ``192``, or ``256`` :term:`bits` long.
 
 .. class:: Camellia(key)
 
@@ -102,7 +102,7 @@ Algorithms
     is not as widely studied or deployed.
 
     :param bytes key: The secret key. This must be kept secret. Either ``128``,
-        ``192``, or ``256`` bits long.
+        ``192``, or ``256`` :term:`bits` long.
 
 .. class:: ChaCha20(key)
 
@@ -120,15 +120,15 @@ Algorithms
     ChaCha20 is a stream cipher used in several IETF protocols. It is
     standardized in :rfc:`7539`.
 
-    :param bytes key: The secret key. This must be kept secret. ``256`` bits
-        (32 bytes) in length.
+    :param bytes key: The secret key. This must be kept secret. ``256``
+        :term:`bits` (32 bytes) in length.
 
     :param bytes nonce: Should be unique, a :term:`nonce`. It is
         critical to never reuse a ``nonce`` with a given key.  Any reuse of a
         nonce with the same key compromises the security of every message
         encrypted with that key. The nonce does not need to be kept secret
-        and may be included with the ciphertext. This must be ``128`` bits in
-        length.
+        and may be included with the ciphertext. This must be ``128``
+        :term:`bits` in length.
 
         .. note::
 
@@ -162,10 +162,11 @@ Algorithms
     is incredibly slow; old applications should consider moving away from it.
 
     :param bytes key: The secret key. This must be kept secret. Either ``64``,
-        ``128``, or ``192`` bits long. DES only uses ``56``, ``112``, or ``168``
-        bits of the key as there is a parity byte in each component of the key.
-        Some writing refers to there being up to three separate keys that are each
-        ``56`` bits long, they can simply be concatenated to produce the full key.
+        ``128``, or ``192`` :term:`bits` long. DES only uses ``56``, ``112``,
+        or ``168`` bits of the key as there is a parity byte in each component
+        of the key.  Some writing refers to there being up to three separate
+        keys that are each ``56`` bits long, they can simply be concatenated
+        to produce the full key.
 
 .. class:: CAST5(key)
 
@@ -173,10 +174,11 @@ Algorithms
 
     CAST5 (also known as CAST-128) is a block cipher approved for use in the
     Canadian government by the `Communications Security Establishment`_. It is
-    a variable key length cipher and supports keys from 40-128 bits in length.
+    a variable key length cipher and supports keys from 40-128 :term:`bits` in
+    length.
 
-    :param bytes key: The secret key, This must be kept secret. 40 to 128 bits
-        in length in increments of 8 bits.
+    :param bytes key: The secret key, This must be kept secret. 40 to 128
+        :term:`bits` in length in increments of 8 bits.
 
 .. class:: SEED(key)
 
@@ -186,8 +188,8 @@ Algorithms
     (KISA). It is defined in :rfc:`4269` and is used broadly throughout South
     Korean industry, but rarely found elsewhere.
 
-    :param bytes key: The secret key. This must be kept secret. ``128`` bits in
-        length.
+    :param bytes key: The secret key. This must be kept secret. ``128``
+        :term:`bits` in length.
 
 Weak ciphers
 ------------
@@ -204,8 +206,8 @@ Weak ciphers
     susceptible to attacks when using weak keys. The author has recommended
     that users of Blowfish move to newer algorithms such as :class:`AES`.
 
-    :param bytes key: The secret key. This must be kept secret. 32 to 448 bits
-        in length in increments of 8 bits.
+    :param bytes key: The secret key. This must be kept secret. 32 to 448
+        :term:`bits` in length in increments of 8 bits.
 
 .. class:: ARC4(key)
 
@@ -214,7 +216,8 @@ Weak ciphers
     mode constructions.
 
     :param bytes key: The secret key. This must be kept secret. Either ``40``,
-        ``56``, ``64``, ``80``, ``128``, ``192``, or ``256`` bits in length.
+        ``56``, ``64``, ``80``, ``128``, ``192``, or ``256`` :term:`bits` in
+        length.
 
     .. doctest::
 
@@ -235,8 +238,8 @@ Weak ciphers
     is susceptible to attacks when using weak keys. It is recommended that you
     do not use this cipher for new applications.
 
-    :param bytes key: The secret key. This must be kept secret. ``128`` bits in
-        length.
+    :param bytes key: The secret key. This must be kept secret. ``128``
+        :term:`bits` in length.
 
 
 .. _symmetric-encryption-modes:
@@ -284,7 +287,7 @@ Modes
     .. warning::
 
         Counter mode is not recommended for use with block ciphers that have a
-        block size of less than 128-bits.
+        block size of less than 128-:term:`bits`.
 
     CTR (Counter) is a mode of operation for block ciphers. It is considered
     cryptographically strong. It transforms a block cipher into a stream
@@ -369,15 +372,16 @@ Modes
         They do not need to be kept secret and they can be included in a
         transmitted message. NIST `recommends a 96-bit IV length`_ for
         performance critical situations but it can be up to 2\ :sup:`64` - 1
-        bits. Do not reuse an ``initialization_vector`` with a given ``key``.
+        :term:`bits`. Do not reuse an ``initialization_vector`` with a given
+        ``key``.
 
     .. note::
 
         Cryptography will generate a 128-bit tag when finalizing encryption.
         You can shorten a tag by truncating it to the desired length but this
         is **not recommended** as it lowers the security margins of the
-        authentication (`NIST SP-800-38D`_ recommends 96-bits or greater).
-        Applications wishing to allow truncation must pass the
+        authentication (`NIST SP-800-38D`_ recommends 96-:term:`bits` or
+        greater).  Applications wishing to allow truncation must pass the
         ``min_tag_length`` parameter.
 
         .. versionchanged:: 0.5
@@ -689,7 +693,7 @@ Interfaces
 
         :type: int
 
-        The number of bits in the key being used.
+        The number of :term:`bits` in the key being used.
 
 
 .. class:: BlockCipherAlgorithm
@@ -700,7 +704,7 @@ Interfaces
 
         :type: int
 
-        The number of bits in a block.
+        The number of :term:`bits` in a block.
 
 Interfaces used by the symmetric cipher modes described in
 :ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`.
diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst
index 9f11332f..3b4f3961 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -24,8 +24,9 @@ codes (HMAC).
 
     HOTP objects take a ``key``, ``length`` and ``algorithm`` parameter. The
     ``key`` should be :doc:`randomly generated bytes </random-numbers>` and is
-    recommended to be 160 bits in length. The ``length`` parameter controls the
-    length of the generated one time password and must be >= 6 and <= 8.
+    recommended to be 160 :term:`bits` in length. The ``length`` parameter
+    controls the length of the generated one time password and must be >= 6
+    and <= 8.
 
     This is an implementation of :rfc:`4226`.
 
@@ -41,8 +42,8 @@ codes (HMAC).
         >>> hotp.verify(hotp_value, 0)
 
     :param bytes key: Per-user secret key. This value must be kept secret
-                      and be at least 128 bits. It is recommended that the
-                      key be 160 bits.
+                      and be at least 128 :term:`bits`. It is recommended that
+                      the key be 160 bits.
     :param int length: Length of generated one time password as ``int``.
     :param cryptography.hazmat.primitives.hashes.HashAlgorithm algorithm: A
         :class:`~cryptography.hazmat.primitives.hashes`
@@ -51,17 +52,17 @@ codes (HMAC).
         :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
         instance.
     :param enforce_key_length: A boolean flag defaulting to True that toggles
-        whether a minimum key length of 128 bits is enforced. This exists to
-        work around the fact that as documented in `Issue #2915`_, the
-        Google Authenticator PAM module by default generates 80 bit keys. If
-        this flag is set to False, the application develop should implement
+        whether a minimum key length of 128 :term:`bits` is enforced. This
+        exists to work around the fact that as documented in `Issue #2915`_,
+        the Google Authenticator PAM module by default generates 80 bit keys.
+        If this flag is set to False, the application develop should implement
         additional checks of the key length before passing it into
         :class:`~cryptography.hazmat.primitives.twofactor.hotp.HOTP`.
 
         .. versionadded:: 1.5
 
     :raises ValueError: This is raised if the provided ``key`` is shorter than
-        128 bits or if the ``length`` parameter is not 6, 7 or 8.
+        128 :term:`bits` or if the ``length`` parameter is not 6, 7 or 8.
     :raises TypeError: This is raised if the provided ``algorithm`` is not
         :class:`~cryptography.hazmat.primitives.hashes.SHA1()`,
         :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or
@@ -163,7 +164,7 @@ similar to the following code.
         >>> totp.verify(totp_value, time_value)
 
     :param bytes key: Per-user secret key. This value must be kept secret
-                      and be at least 128 bits. It is recommended that the
+                      and be at least 128 :term:`bits`. It is recommended that the
                       key be 160 bits.
     :param int length: Length of generated one time password as ``int``.
     :param cryptography.hazmat.primitives.hashes.HashAlgorithm algorithm: A
@@ -174,7 +175,7 @@ similar to the following code.
         :class:`~cryptography.hazmat.backends.interfaces.HMACBackend`
         instance.
     :param enforce_key_length: A boolean flag defaulting to True that toggles
-        whether a minimum key length of 128 bits is enforced. This exists to
+        whether a minimum key length of 128 :term:`bits` is enforced. This exists to
         work around the fact that as documented in `Issue #2915`_, the
         Google Authenticator PAM module by default generates 80 bit keys. If
         this flag is set to False, the application develop should implement
@@ -183,7 +184,7 @@ similar to the following code.
 
         .. versionadded:: 1.5
     :raises ValueError: This is raised if the provided ``key`` is shorter than
-        128 bits or if the ``length`` parameter is not 6, 7 or 8.
+        128 :term:`bits` or if the ``length`` parameter is not 6, 7 or 8.
     :raises TypeError: This is raised if the provided ``algorithm`` is not
         :class:`~cryptography.hazmat.primitives.hashes.SHA1()`,
         :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or