diff options
author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2013-12-12 15:57:58 -0800 |
---|---|---|
committer | Paul Kehrer <paul.l.kehrer@gmail.com> | 2013-12-12 15:57:58 -0800 |
commit | 6c0eef73f7e7dc1a21a36e1ca6979f186dfa964e (patch) | |
tree | 37b6270ff5d82b485c9cb7f7c2540d71aa845e11 | |
parent | 7d78a5b9f3dd4c31efc3f07769f45ace5aefee86 (diff) | |
parent | 2e1d5ae56823e34114869f48707958a28891f3c2 (diff) | |
download | cryptography-6c0eef73f7e7dc1a21a36e1ca6979f186dfa964e.tar.gz cryptography-6c0eef73f7e7dc1a21a36e1ca6979f186dfa964e.tar.bz2 cryptography-6c0eef73f7e7dc1a21a36e1ca6979f186dfa964e.zip |
Merge pull request #299 from alex/api-style-guide
Api style guide
-rw-r--r-- | docs/contributing.rst | 34 |
1 files changed, 34 insertions, 0 deletions
diff --git a/docs/contributing.rst b/docs/contributing.rst index 934bb45a..09833ed3 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -47,6 +47,40 @@ Additionally, every Python code file must contain from __future__ import absolute_import, division, print_function +API Considerations +~~~~~~~~~~~~~~~~~~ + +Most projects' APIs are designed with a philosophy of "make easy things easy, +and make hard things possible". One of the perils of writing cryptographic code +is that code that is secure looks just like code that isn't, and produces +results that are also difficult to distinguish. As a result ``cryptography`` +has, as a design philosophy: "make it hard to do insecure things". Here are a +few strategies for API design which should be both followed, and should inspire +other API choices: + +If it is incorrect to ignore the result of a method, it should raise an +exception, and not return a boolean ``True``/``False`` flag. For example, a +method to verify a signature should raise ``InvalidSignature``, and not return +whether the signature was valid. + +.. code-block:: python + + # This is bad. + def verify(sig): + # ... + return is_valid + + # Good! + def verify(sig): + # ... + if not is_valid: + raise InvalidSignature + +APIs at the :doc:`/hazmat/primitives/index` layer should always take an +explicit backend, APIs at the recipes layer should automatically use the +:func:`~cryptography.hazmat.bindings.default_backend`, but optionally allow +specifiying a different backend. + C bindings ~~~~~~~~~~ |