diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/primitives/aead.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 14 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/padding.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 56 | ||||
| -rw-r--r-- | docs/hazmat/primitives/twofactor.rst | 25 |
7 files changed, 62 insertions, 57 deletions
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 |