Merge pull request #1985 from eeshangarg/documentation-1971
Docs for CTR and GCM should say that IV/nonce must be unique
diff --git a/docs/glossary.rst b/docs/glossary.rst
index dc6f3eb..202fa2d 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -64,3 +64,11 @@
text
This type corresponds to ``unicode`` on Python 2 and ``str`` on Python
3. This is equivalent to ``six.text_type``.
+
+ nonce
+ A nonce is a **n**\ umber used **once**. Nonces are used in many
+ cryptographic protocols. Generally, a nonce does not have to be secret
+ or unpredictable, but it must be unique. A nonce is often a random
+ or pseudo-random number (see :doc:`Random number generation
+ </random-numbers>`). Since a nonce does not have to be unpredictable,
+ it can also take a form of a counter.
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 4748689..309c6fd 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -240,7 +240,7 @@
**This mode does not require padding.**
- :param bytes nonce: Should be :doc:`random bytes </random-numbers>`. It is
+ :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. Must be the same number of bytes as the
@@ -305,12 +305,11 @@
**This mode does not require padding.**
- :param bytes initialization_vector: Must be :doc:`random bytes
- </random-numbers>`. 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``.
+ :param bytes initialization_vector: Must be unique, a :term:`nonce`.
+ 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``.
.. note::
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index badb500..8151013 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -40,6 +40,7 @@
naïve
namespace
namespaces
+Nonces
online
paddings
pickleable