diff --git a/docs/secret.rst b/docs/secret.rst index 1794ac9461eeddff6bcd616d26bbb31d71eb9a2e..ed661f057276ba6b207f2fb3ef588297b27be2c3 100644 --- a/docs/secret.rst +++ b/docs/secret.rst @@ -42,18 +42,45 @@ Example plaintext = box.decrypt(ciphertext, nonce) -Usage Information ------------------ - -* :class:`~nacl.secret.SecretBox` requires a 32 byte key that must be kept - secret. It is the combination to your "safe" and anyone with this key will - be able to decrypt the data. -* :class:`~nacl.secret.SecretBox` requires a new 24 bytes nonce with every - encrypted message. This nonce is *not* secret and be freely transfered or - stored in plaintext alongside the ciphertext. However it is absolutely - imperative that you **NEVER** reuse a nonce with the same key. Reusing the - nonce with the same key provides enough information for an attacker - to decrypt any and all messages made with your key. +Requirements +------------ + +Key +~~~ + +The 32 bytes key given to :class:`~nacl.secret.SecretBox` must be kept secret. +It is the combination to your "safe" and anyone with this key will be able to +decrypt the data, or encrypt new data. + + +Nonce +~~~~~ + +The 24 bytes nonce (Number used once) given to :meth:`~nacl.secret.SecretBox.encrypt` +and :meth:`~nacl.secret.SecretBox.decrypt` must **NEVER** be reused for a +particular key. Reusing the nonce means an attacker will have enough information +to recover your secret key and encrypt or decrypt arbitrary messages. A nonce +is not considered secret and may be freely transmitted or stored in plaintext +alongside the ciphertext. + +A nonce does not need to be random, nor does the method of generating them need +to be secret. A nonce could simply be a counter incremented with each message +encrypted. + +Both the sender and the receiver should record every nonce both that they've +used and they've received from the other. They should reject any message which +reuses a nonce and they should make absolutely sure never to reuse a nonce. It +is not enough to simply use a random value and hope that it's not being reused +(simply generating random values would open up the system to a +`Birthday Attack <https://en.wikipedia.org/wiki/Birthday_attack>`_). + +One good method of generating nonces is for each person to pick a unique prefix, +for example ``b"p1"`` and ``b"p2"``. When each person generates a nonce they +prefix it, so instead of ``nacl.random(24)`` you'd do ``b"p1" + nacl.random(22)``. +This prefix serves as a guarantee that no two messages from different people +will inadvertently overlap nonces while in transit. They should still record +every nonce they've personally used and every nonce they've received to prevent +reuse or replays. Reference