diff --git a/docs/conf.py b/docs/conf.py index 87781d7934bf7a7ba7e70a65d6e56b49ad103cd4..ec2d8e56bd8a8d1e86711c47fb74ab471081c103 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,6 +10,11 @@ import os import sys +try: + import sphinx_rtd_theme +except ImportError: + sphinx_rtd_theme = None + # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. @@ -95,7 +100,11 @@ pygments_style = "sphinx" # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "default" +if sphinx_rtd_theme: + html_theme = "sphinx_rtd_theme" + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +else: + html_theme = "default" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the diff --git a/docs/index.rst b/docs/index.rst index b372b09ed172652245fdea83bf4e09d9bdd61431..c8ce3d36d06fbbb005c4987c9f9a6067520098d1 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -36,4 +36,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/docs/public.rst b/docs/public.rst index 7b165ceaa5ce597a9ca97e1a511a7a8154f4fc25..fa6b4cdae303fa9a40ba923518a1cb0cc91dd1c3 100644 --- a/docs/public.rst +++ b/docs/public.rst @@ -1,6 +1,8 @@ Public Key Encryption ===================== +.. currentmodule:: nacl.public + Imagine Alice wants something valuable shipped to her. Because it's valuable, she wants to make sure it arrives securely (i.e. hasn't been opened or tampered with) and that it's not a forgery (i.e. it's actually from the sender @@ -83,14 +85,83 @@ with equal that from (pkbob, skalice). This is how the system works: Reference --------- -.. autoclass:: nacl.public.PublicKey - :members: +.. class:: PublicKey(public_key, encoder) + + The public key counterpart to an Curve25519 + :class:`~nacl.public.PrivateKey` for encrypting messages. + + :param bytes public_key: Encoded Curve25519 public key. + :param encoder: A class that is able to decode the ``public_key``. + +.. class:: PrivateKey(private_key, encoder) + + Private key for decrypting messages using the Curve25519 algorithm. + + .. warning:: This **must** be protected and remain secret. Anyone who + knows the value of your :class:`~nacl.public.PrivateKey` can decrypt + any message encrypted by the corresponding + :class:`~nacl.public.PublicKey` + + :param bytes private_key: The private key used to decrypt messages. + :param encoder: A class that is able to decode the ``private_key``. + + .. attribute:: public_key + + An instance of :class:`~.nacl.public.PublicKey` that corresponds with + the private key. + + .. classmethod:: generate() + + Generates a random :class:`~nacl.public.PrivateKey` object + + :return: An instance of :class:`~nacl.public.PrivateKey`. + +.. class:: Box(private_key, public_key) + + The Box class boxes and unboxes messages between a pair of keys + + The ciphertexts generated by :class:`~nacl.public.Box` include a 16 + byte authenticator which is checked as part of the decryption. An invalid + authenticator will cause the decrypt function to raise an exception. The + authenticator is not a signature. Once you've decrypted the message you've + demonstrated the ability to create arbitrary valid message, so messages you + send are repudiable. For non-repudiable messages, sign them after + encryption. + + :param private_key: An instance of :class:`~nacl.public.PrivateKey` used + to encrypt and decrypt messages + :param public_key: An instance of :class:`~nacl.public.PublicKey` used to + encrypt and decrypt messages + + .. classmethod:: decode(encoded, encoder) + + Decodes a serialized :class:`~nacl.public.Box`. + + :return: An instance of :class:`~nacl.public.Box`. + + .. method:: encrypt(plaintext, nonce, encoder) + + Encrypts the plaintext message using the given `nonce` and returns + the ciphertext encoded with the encoder. + + .. warning:: It is **VITALLY** important that the nonce is a nonce, + i.e. it is a number used only once for any given key. If you + fail to do this, you compromise the privacy of the messages + encrypted. + + :param bytes plaintext: The plaintext message to encrypt. + :param bytes nonce: The nonce to use in the encryption. + :param encoder: A class that is able to decode the ciphertext. + + :return: An instance of :class:`~nacl.utils.EncryptedMessage`. + + .. method:: decrypt(ciphertext, nonce, encoder) -.. autoclass:: nacl.public.PrivateKey - :members: + Decrypts the ciphertext using the given nonce and returns the + plaintext message. -.. autoclass:: nacl.public.Box - :members: + :param bytes ciphertext: The encrypted message to decrypt. + :param bytes nonce: The nonce to use in the decryption. + :param encoder: A class that is able to decode the plaintext. -.. autoclass:: nacl.utils.EncryptedMessage - :members: + :return bytes: The decrypted plaintext. diff --git a/src/nacl/public.py b/src/nacl/public.py index c76bc09199dc81ef4add746776ea6653525b7f26..f6ab8920f61a6abaaa2e545fba3c039bafdfc49b 100644 --- a/src/nacl/public.py +++ b/src/nacl/public.py @@ -22,15 +22,6 @@ from nacl.utils import EncryptedMessage, StringFixer, random class PublicKey(encoding.Encodable, StringFixer, object): - """ - The public key counterpart to an Curve25519 :class:`nacl.public.PrivateKey` - for encrypting messages. - - :param public_key: [:class:`bytes`] Encoded Curve25519 public key - :param encoder: A class that is able to decode the `public_key` - - :cvar SIZE: The size that the public key is required to be - """ SIZE = nacl.c.crypto_box_PUBLICKEYBYTES @@ -46,19 +37,6 @@ class PublicKey(encoding.Encodable, StringFixer, object): class PrivateKey(encoding.Encodable, StringFixer, object): - """ - Private key for decrypting messages using the Curve25519 algorithm. - - .. warning:: This **must** be protected and remain secret. Anyone who - knows the value of your :class:`~nacl.public.PrivateKey` can decrypt - any message encrypted by the corresponding - :class:`~nacl.public.PublicKey` - - :param private_key: The private key used to decrypt messages - :param encoder: The encoder class used to decode the given keys - - :cvar SIZE: The size that the private key is required to be - """ SIZE = nacl.c.crypto_box_SECRETKEYBYTES @@ -81,33 +59,10 @@ class PrivateKey(encoding.Encodable, StringFixer, object): @classmethod def generate(cls): - """ - Generates a random :class:`~nacl.public.PrivateKey` object - - :rtype: :class:`~nacl.public.PrivateKey` - """ return cls(random(PrivateKey.SIZE), encoder=encoding.RawEncoder) class Box(encoding.Encodable, StringFixer, object): - """ - The Box class boxes and unboxes messages between a pair of keys - - The ciphertexts generated by :class:`~nacl.public.Box` include a 16 - byte authenticator which is checked as part of the decryption. An invalid - authenticator will cause the decrypt function to raise an exception. The - authenticator is not a signature. Once you've decrypted the message you've - demonstrated the ability to create arbitrary valid message, so messages you - send are repudiable. For non-repudiable messages, sign them after - encryption. - - :param private_key: :class:`~nacl.public.PrivateKey` used to encrypt and - decrypt messages - :param public_key: :class:`~nacl.public.PublicKey` used to encrypt and - decrypt messages - - :cvar NONCE_SIZE: The size that the nonce is required to be. - """ NONCE_SIZE = nacl.c.crypto_box_NONCEBYTES @@ -134,19 +89,7 @@ class Box(encoding.Encodable, StringFixer, object): return box def encrypt(self, plaintext, nonce, encoder=encoding.RawEncoder): - """ - Encrypts the plaintext message using the given `nonce` and returns - the ciphertext encoded with the encoder. - - .. warning:: It is **VITALLY** important that the nonce is a nonce, - i.e. it is a number used only once for any given key. If you fail - to do this, you compromise the privacy of the messages encrypted. - - :param plaintext: [:class:`bytes`] The plaintext message to encrypt - :param nonce: [:class:`bytes`] The nonce to use in the encryption - :param encoder: The encoder to use to encode the ciphertext - :rtype: [:class:`nacl.utils.EncryptedMessage`] - """ + if len(nonce) != self.NONCE_SIZE: raise ValueError("The nonce must be exactly %s bytes long" % self.NONCE_SIZE) @@ -167,16 +110,7 @@ class Box(encoding.Encodable, StringFixer, object): ) def decrypt(self, ciphertext, nonce=None, encoder=encoding.RawEncoder): - """ - Decrypts the ciphertext using the given nonce and returns the - plaintext message. - - :param ciphertext: [:class:`bytes`] The encrypted message to decrypt - :param nonce: [:class:`bytes`] The nonce used when encrypting the - ciphertext - :param encoder: The encoder used to decode the ciphertext. - :rtype: [:class:`bytes`] - """ + # Decode our ciphertext ciphertext = encoder.decode(ciphertext) diff --git a/src/nacl/utils.py b/src/nacl/utils.py index 4d555aa15f9f69d103745d46f65c655456b2cbc2..b4b7ca928f61bc35bc8364b00ed596f4ce5368a3 100644 --- a/src/nacl/utils.py +++ b/src/nacl/utils.py @@ -20,10 +20,6 @@ import nacl.c class EncryptedMessage(six.binary_type): - """ - A bytes subclass that holds a messaged that has been encrypted by a - :class:`SecretBox`. - """ @classmethod def _from_parts(cls, nonce, ciphertext, combined): @@ -34,16 +30,10 @@ class EncryptedMessage(six.binary_type): @property def nonce(self): - """ - The nonce used during the encryption of the :class:`EncryptedMessage`. - """ return self._nonce @property def ciphertext(self): - """ - The ciphertext contained within the :class:`EncryptedMessage`. - """ return self._ciphertext diff --git a/tox.ini b/tox.ini index b12e47ca3da5cf345887a1daef44ed70508cfd55..d778dfba3fcafb2be9725ab65a9cac6431d47837 100644 --- a/tox.ini +++ b/tox.ini @@ -13,6 +13,7 @@ commands = [testenv:docs] deps = sphinx + sphinx_rtd_theme basepython = python2.7 commands = sphinx-build -W -b html -d {envtmpdir}/doctrees docs docs/_build/html