From e0b2f0ddf91bd99eef5579285d1f7afaf6872fcc Mon Sep 17 00:00:00 2001
From: Donald Stufft <donald@stufft.io>
Date: Sat, 9 Mar 2013 21:16:27 -0500
Subject: [PATCH] Document the PyNaCl encoding system
---
docs/encoding.rst | 58 +++++++++++++++++++++++++++++++++++++++++++++++
docs/index.rst | 9 ++++++++
docs/signing.rst | 7 +++---
nacl/signing.py | 11 ++++-----
4 files changed, 75 insertions(+), 10 deletions(-)
create mode 100644 docs/encoding.rst
diff --git a/docs/encoding.rst b/docs/encoding.rst
new file mode 100644
index 00000000..d698cd3e
--- /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 c987ffbf..6be9babe 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 8a67a8ca..f4e24950 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 bc196190..f08e3abf 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)
--
GitLab