Merge pull request #126 from warner/restore-docstrings

restore docstrings for public, secret, and utils

src/nacl/public.py

@@ -20,6 +20,15 @@
 
 
 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.bindings.crypto_box_PUBLICKEYBYTES
 
@@ -35,6 +44,19 @@ def __bytes__(self):
 
 
 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.bindings.crypto_box_SECRETKEYBYTES
 
@@ -57,10 +79,33 @@ def __bytes__(self):
 
     @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.bindings.crypto_box_NONCEBYTES
 
@@ -87,7 +132,19 @@ def decode(cls, encoded, encoder=encoding.RawEncoder):
         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)
@@ -108,7 +165,16 @@ def encrypt(self, plaintext, nonce, encoder=encoding.RawEncoder):
         )
 
     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)
 

src/nacl/secret.py

@@ -20,6 +20,24 @@
 
 
 class SecretBox(encoding.Encodable, StringFixer, object):
+    """
+    The SecretBox class encrypts and decrypts messages using the given secret
+    key.
+
+    The ciphertexts generated by :class:`~nacl.secret.Secretbox` 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 key: The secret key used to encrypt and decrypt messages
+    :param encoder: The encoder class used to decode the given key
+
+    :cvar KEY_SIZE: The size that the key is required to be.
+    :cvar NONCE_SIZE: The size that the nonce is required to be.
+    """
 
     KEY_SIZE = nacl.bindings.crypto_secretbox_KEYBYTES
     NONCE_SIZE = nacl.bindings.crypto_secretbox_NONCEBYTES
@@ -39,7 +57,21 @@ def __bytes__(self):
         return self._key
 
     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.
+            Give your nonces a different prefix, or have one side use an odd
+            counter and one an even counter. Just make sure they are different.
+
+        :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,
@@ -58,7 +90,16 @@ def encrypt(self, plaintext, nonce, encoder=encoding.RawEncoder):
         )
 
     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)
 

src/nacl/utils.py

@@ -20,6 +20,10 @@
 
 
 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):
@@ -30,10 +34,16 @@ def _from_parts(cls, nonce, ciphertext, combined):
 
     @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