diff --git a/docs/encoding.rst b/docs/encoding.rst new file mode 100644 index 0000000000000000000000000000000000000000..d698cd3e17aa5e257fb8a5d4caf4065fb4f84acf --- /dev/null +++ b/docs/encoding.rst @@ -0,0 +1,58 @@ +Encoders +======== + +PyNaCl supports a simple method of encoding and decoding messages in different +formats. Encoders are simple classes with staticmethods that encode/decode and +are typically passed as a keyword argument `encoder` to various methods. + +For example you can generate a signing key and encode it in hex with: + +.. code:: python + + hex_key = nacl.signing.SigningKey.generate().encode(encoder=nacl.encoding.HexEncoder) + +Then you can later decode it from hex: + +.. code:: python + + signing_key = nacl.signing.SigningKey(hex_key, encoder=nacl.encoding.HexEncoder) + + +Built in Encoders +----------------- + +.. autoclass:: nacl.encoding.RawEncoder + :members: + +.. autoclass:: nacl.encoding.HexEncoder + :members: + +.. autoclass:: nacl.encoding.Base16Encoder + :members: + +.. autoclass:: nacl.encoding.Base32Encoder + :members: + +.. autoclass:: nacl.encoding.Base64Encoder + :members: + + +Defining your own Encoder +------------------------- + +Defining your own encoder is easy. Each encoder is simply a class with 2 static +methods. For example here is the hex encoder: + +.. code:: python + + import binascii + + class HexEncoder(object): + + @staticmethod + def encode(data): + return binascii.hexlify(data) + + @staticmethod + def decode(data): + return binascii.unhexlify(data) diff --git a/docs/index.rst b/docs/index.rst index c987ffbf29cde87ca443be70fc9d622fbfa8f050..6be9babe475bb5974449dd8b13fb582799513859 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,6 +9,15 @@ Contents: signing +Support Features +---------------- + +.. toctree:: + :maxdepth: 2 + + encoding + + Api Documentation ----------------- diff --git a/docs/signing.rst b/docs/signing.rst index 8a67a8ca5f25e7de0e9c4e58e2824f7d8f22617b..f4e24950c24f5b6d05fe55871295632d8d8ce63a 100644 --- a/docs/signing.rst +++ b/docs/signing.rst @@ -19,7 +19,7 @@ Signer's perspective (:class:`~nacl.signing.SigningKey`) .. code:: python - import binascii + import nacl.encoding import nacl.signing # Generate a new random signing key @@ -32,17 +32,16 @@ Signer's perspective (:class:`~nacl.signing.SigningKey`) verify_key = signing_key.verify_key # Serialize the verify key to send it to a third party - binascii.hexlify(bytes(verify_key)) + verify_key_hex = verify_key.encode(encoder=nacl.encoding.HexEncoder) Verifier's perspective (:class:`~nacl.signing.VerifyKey`) .. code:: python - import binascii import nacl.signing # Create a VerifyKey object from a hex serialized public key - verify_key = nacl.signing.VerifyKey(binascii.unhexlify(verify_key_hex)) + verify_key = nacl.signing.VerifyKey(verify_key_hex, encoder=nacl.encoding.HexEncoder) # Check the validity of a message's signature # Will raise nacl.signing.BadSignatureError if the signature check fails diff --git a/nacl/signing.py b/nacl/signing.py index bc196190c6659b07c04c39813f24a1b44ff5ca40..f08e3abf6164e92b7fa733cf34a950875cc3b1ba 100644 --- a/nacl/signing.py +++ b/nacl/signing.py @@ -47,7 +47,7 @@ class VerifyKey(encoding.Encodable, six.StringFixer, object): signatures. :param key: [:class:`bytes`] Serialized Ed25519 public key - :param encoding: [:class:`str`] The encoding that the key is encoded with + :param encoder: A class that is able to decode the `key` """ def __init__(self, key, encoder=encoding.RawEncoder): @@ -73,8 +73,8 @@ class VerifyKey(encoding.Encodable, six.StringFixer, object): 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 encoding: [:class:`str`] The encoding that the secret message - and signature is encoded with. + :param encoder: A class that is able to decode the secret message and + signature. :rtype: :class:`bytes` """ if signature is not None: @@ -107,7 +107,7 @@ class SigningKey(encoding.Encodable, six.StringFixer, object): masquerade as you. :param seed: [:class:`bytes`] Random 32-byte value (i.e. private key) - :param encoding: [:class:`str`] The encoding that the seed is encoded with + :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. @@ -155,8 +155,7 @@ class SigningKey(encoding.Encodable, six.StringFixer, object): Sign a message using this key. :param message: [:class:`bytes`] The data to be signed. - :param encoding: [:class:`str`] The encoding to encode the signed - message with. + :param encoder: A class that is used to encode the signed message. :rtype: :class:`~nacl.signing.SignedMessage` """ sm = nacl.ffi.new("unsigned char[]", len(message) + nacl.lib.crypto_sign_BYTES)