diff --git a/src/nacl/signing.py b/src/nacl/signing.py index 53e69a5a4fb3bbe9bba7c19b58e2724381d457e0..76ce0a4cd7710df259ac242e213b877fe9f6c4b3 100644 --- a/src/nacl/signing.py +++ b/src/nacl/signing.py @@ -22,6 +22,10 @@ from nacl.utils import StringFixer, random class SignedMessage(six.binary_type): + """ + A bytes subclass that holds a messaged that has been signed by a + :class:`SigningKey`. + """ @classmethod def _from_parts(cls, signature, message, combined): @@ -32,14 +36,27 @@ class SignedMessage(six.binary_type): @property def signature(self): + """ + The signature contained within the :class:`SignedMessage`. + """ return self._signature @property def message(self): + """ + The message contained within the :class:`SignedMessage`. + """ return self._message class VerifyKey(encoding.Encodable, StringFixer, object): + """ + The public key counterpart to an Ed25519 SigningKey for producing digital + signatures. + + :param key: [:class:`bytes`] Serialized Ed25519 public key + :param encoder: A class that is able to decode the `key` + """ def __init__(self, key, encoder=encoding.RawEncoder): # Decode the key @@ -57,6 +74,19 @@ class VerifyKey(encoding.Encodable, StringFixer, object): return self._key def verify(self, smessage, signature=None, encoder=encoding.RawEncoder): + """ + Verifies the signature of a signed message, returning the message + if it has not been tampered with else raising + :class:`~nacl.signing.BadSignatureError`. + + :param smessage: [:class:`bytes`] Either the original messaged or a + signature and message concated together. + :param signature: [:class:`bytes`] If an unsigned message is given for + smessage then the detached signature must be provded. + :param encoder: A class that is able to decode the secret message and + signature. + :rtype: :class:`bytes` + """ if signature is not None: # If we were given the message and signature separately, combine # them. @@ -69,6 +99,23 @@ class VerifyKey(encoding.Encodable, StringFixer, object): class SigningKey(encoding.Encodable, StringFixer, object): + """ + Private key for producing digital signatures using the Ed25519 algorithm. + + Signing keys are produced from a 32-byte (256-bit) random seed value. This + value can be passed into the :class:`~nacl.signing.SigningKey` as a + :func:`bytes` whose length is 32. + + .. warning:: This **must** be protected and remain secret. Anyone who knows + the value of your :class:`~nacl.signing.SigningKey` or it's seed can + masquerade as you. + + :param seed: [:class:`bytes`] Random 32-byte value (i.e. private key) + :param encoder: A class that is able to decode the seed + + :ivar: verify_key: [:class:`~nacl.signing.VerifyKey`] The verify + (i.e. public) key that corresponds with this signing key. + """ def __init__(self, seed, encoder=encoding.RawEncoder): # Decode the seed @@ -92,12 +139,24 @@ class SigningKey(encoding.Encodable, StringFixer, object): @classmethod def generate(cls): + """ + Generates a random :class:`~nacl.signing.SingingKey` object. + + :rtype: :class:`~nacl.signing.SigningKey` + """ return cls( random(nacl.c.crypto_sign_SEEDBYTES), encoder=encoding.RawEncoder, ) def sign(self, message, encoder=encoding.RawEncoder): + """ + Sign a message using this key. + + :param message: [:class:`bytes`] The data to be signed. + :param encoder: A class that is used to encode the signed message. + :rtype: :class:`~nacl.signing.SignedMessage` + """ raw_signed = nacl.c.crypto_sign(message, self._signing_key) signature = encoder.encode(raw_signed[:nacl.c.crypto_sign_BYTES])