let's talk about bits baby (#3956)
diff --git a/docs/glossary.rst b/docs/glossary.rst
index 3a1280a..df32760 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -85,5 +85,14 @@
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 3c45b52..7b01f74 100644
--- a/docs/hazmat/primitives/aead.rst
+++ b/docs/hazmat/primitives/aead.rst
@@ -122,7 +122,7 @@
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 @@
``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 57b4a96..9da7273 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -17,8 +17,8 @@
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 50c38e3..0bb74c6 100644
--- a/docs/hazmat/primitives/asymmetric/ec.rst
+++ b/docs/hazmat/primitives/asymmetric/ec.rst
@@ -268,7 +268,7 @@
.. 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 @@
: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 @@
: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 @@
: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 a49b4d3..607cebb 100644
--- a/docs/hazmat/primitives/asymmetric/rsa.rst
+++ b/docs/hazmat/primitives/asymmetric/rsa.rst
@@ -19,9 +19,9 @@
.. 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 @@
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 45bcc13..e49fc49 100644
--- a/docs/hazmat/primitives/padding.rst
+++ b/docs/hazmat/primitives/padding.rst
@@ -36,8 +36,8 @@
>>> 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 @@
>>> 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 2635e75..aa577f0 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -93,7 +93,7 @@
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 @@
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 @@
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 @@
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 @@
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 @@
(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 @@
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 @@
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 @@
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 @@
.. 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 @@
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 @@
: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 @@
: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 9f11332..3b4f396 100644
--- a/docs/hazmat/primitives/twofactor.rst
+++ b/docs/hazmat/primitives/twofactor.rst
@@ -24,8 +24,9 @@
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 @@
>>> 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 @@
: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 @@
>>> 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 @@
: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 @@
.. 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