design an object-oriented interface

[warner]

In my other NaCl bindings, I've found it useful to provide an object-oriented API, in addition to the raw functions that take and return bytestrings. Benefits include: it's harder to accidentally get the arguments in the wrong order, harder to confuse public keys with private keys, and there's more room to add helper functions like base64-encoders.

For the Curve25519 "Box" object, it also provides a very natural place to stash the pre-computed shared secret (e.g. call crypto_box_beforenm in the constructor, and crypto_box_afternm in the encrypt() method). I'd also like to see nonce management made easier: the default Box(..).encrypt() method should generate a random nonce for you if you don't provide one, so the default is safe. To do that, however, it would need to automatically prepend the nonce to the output ciphertext, or return a (nonce, ciphertext) tuple, both of which differ from the pattern used by the underlying crypto_box(). We'll need to experiment.

This issue is to design this API and then implement it. My plan is to make it live in some second-level namespaces like from nacl.box import PrivateKey, Box and from nacl.sign import SigningKey, VerifyingKey.

[warner]

It should match the API provided by the libsodium-powered pynacl, e.g. public-key box/unbox in https://github.com/pyca/pynacl/blob/master/docs/public.rst . Ideally, python-tweetnacl would be a drop-in replacement. The benefits of python-tweetnacl would be pip-installability (pynacl depends on having an externally-installed libsodium first) and smaller code size. pynacl could be faster (it includes larger-but-more-optimized nacl code, with runtime selection) and support for more algorithms (libsodium adds SipHash and BLAKE2).