From e6466a50ea3ee6798c904649d6c67e01eef96b14 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 18 Oct 2013 14:53:04 -0700 Subject: Document our style guide for C bindings --- docs/contributing.rst | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 2d8fceeb..7bb7c43e 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -20,8 +20,8 @@ devastating, ``cryptography`` has a strict code review policy: * Patches must *never* be pushed directly to ``master``, all changes (even the most trivial typo fixes!) must be submitted as a pull request. * A committer may *never* merge their own pull request, a second party must - merge their changes. If multiple people work on a pull request, the merger - may not be any of them. + merge their changes. If multiple people work on a pull request, it must be + merged by someone who did not work on it. * A patch which breaks tests, or introduces regressions by changing or removing existing tests should not be merged. Tests must always be passing on ``master``. @@ -50,6 +50,39 @@ Additionally, every Python code file must contain from __future__ import absolute_import, division, print_function +C bindings +---------- + +When binding C code with ``cffi`` we have our own style guide, it's pretty +simple. + +Don't name parameters: + +.. code-block:: c + + // Good + long f(long); + // Bad + long f(long x); + +Don't include stray ``void`` parameters: + +.. code-block:: c + + // Good + long f(); + // Bad + long f(void); + +Wrap lines at 80 characters like so: + +.. code-block:: c + + // Pretend this went to 80 characters + long f(long, long, + int *) + + Documentation ------------- -- cgit v1.2.3 From 1e8744a5bf9dc09215f9aed9606081fc6eee517a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Fri, 18 Oct 2013 14:57:18 -0700 Subject: DOcument the use of spaces here --- docs/contributing.rst | 9 +++++++++ 1 file changed, 9 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 7bb7c43e..b125d1af 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -82,6 +82,15 @@ Wrap lines at 80 characters like so: long f(long, long, int *) +Include a space after commas between parameters: + +.. code-block:: c + + // Good + long f(int, char *) + // Bad + long f(int,char *) + Documentation ------------- -- cgit v1.2.3 From 99b69d94cf95b39164dd9d35ff7a463b7a1b7f20 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 19 Oct 2013 17:52:58 -0700 Subject: Start better documenting our security procedure --- docs/contributing.rst | 7 ++----- docs/index.rst | 1 + docs/security.rst | 12 ++++++++++++ 3 files changed, 15 insertions(+), 5 deletions(-) create mode 100644 docs/security.rst (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index b125d1af..dc8ce453 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -32,11 +32,8 @@ devastating, ``cryptography`` has a strict code review policy: The purpose of these policies is to minimize the chances we merge a change which jeopardizes our users' security. -We do not yet have a formal security contact. To report security issues in -``cryptography`` you should email ``alex.gaynor@gmail.com``, messages may be -encrypted with PGP to key fingerprint -``E27D 4AA0 1651 72CB C5D2 AF2B 125F 5C67 DFE9 4084`` (this public key is -available from most commonly-used keyservers). +If you believe you've identified a security issue in ``cryptography``, please +follow the directions on the :doc:`security page `. Code ---- diff --git a/docs/index.rst b/docs/index.rst index 5cc455f6..a868a5d6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -34,4 +34,5 @@ Contents primitives/index bindings/index contributing + security community diff --git a/docs/security.rst b/docs/security.rst new file mode 100644 index 00000000..36c8e0f7 --- /dev/null +++ b/docs/security.rst @@ -0,0 +1,12 @@ +Security +======== + +We take the security of ``cryptography`` seriously. If you believe you've +identified a security issue in it, please report it to +``alex.gaynor@gmail.com``. Message may be encrypted with PGP using key +fingerprint ``E27D 4AA0 1651 72CB C5D2 AF2B 125F 5C67 DFE9 4084`` (this public +key is available from most commonly-used keyservers). + +Once you’ve submitted an issue via email, you should receive an acknowledgment +within 48 hours, and depending on the action to be taken, you may receive +further followup emails. -- cgit v1.2.3 From 3ed80ba1c1773a0e45538e432573d91cfb388b0f Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Oct 2013 20:00:26 -0500 Subject: add struct style info to docs --- docs/contributing.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index b125d1af..fe87ac29 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -65,6 +65,16 @@ Don't name parameters: // Bad long f(long x); +...unless they're inside a struct: + +.. code-block:: c + + struct my_struct { + char *name; + int number; + ...; + }; + Don't include stray ``void`` parameters: .. code-block:: c -- cgit v1.2.3 From bf9df01971d5d154c170fa873d9829e5cb2795ec Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Sat, 19 Oct 2013 22:39:44 -0400 Subject: Use the https://cryptography.io domain name --- docs/community.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/community.rst b/docs/community.rst index 86ba5055..552318da 100644 --- a/docs/community.rst +++ b/docs/community.rst @@ -12,4 +12,4 @@ You can find ``cryptography`` all over the web: .. _`Mailing list`: https://mail.python.org/mailman/listinfo/cryptography-dev .. _`Source code`: https://github.com/pyca/cryptography .. _`Issue tracker`: https://github.com/pyca/cryptography/issues -.. _`Documentation`: https://cryptography.readthedocs.org/ +.. _`Documentation`: https://cryptography.io/ -- cgit v1.2.3 From 36e7d0df315dca887f5b073e17209ee3eeb5a576 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 18 Oct 2013 18:54:40 -0500 Subject: MD5 support + documentation for all hashes --- docs/primitives/cryptographic-hashes.rst | 164 +++++++++++++++++++++++++++++++ docs/primitives/index.rst | 1 + 2 files changed, 165 insertions(+) create mode 100644 docs/primitives/cryptographic-hashes.rst (limited to 'docs') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst new file mode 100644 index 00000000..1499f762 --- /dev/null +++ b/docs/primitives/cryptographic-hashes.rst @@ -0,0 +1,164 @@ +Message Digests +==================== + +SHA-1 +~~~~~~~ + +.. attention:: + + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. + +.. class:: cryptography.primitives.hashes.SHA1() + + SHA-1 is a cryptographic hash function standardized by NIST. It has a + 160-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + + +SHA-2 Family +~~~~~~~ + +.. class:: cryptography.primitives.hashes.SHA224() + + SHA-224 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 224-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA256() + + SHA-256 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 256-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA384() + + SHA-384 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 384-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +.. class:: cryptography.primitives.hashes.SHA512() + + SHA-512 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 512-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +RIPEMD160 +~~~~~~~ + +.. class:: cryptography.primitives.hashes.RIPEMD160() + + RIPEMD160 is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 160-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +Whirlpool +~~~~~~~ + +.. class:: cryptography.primitives.hashes.Whirlpool() + + Whirlpool is a cryptographic hash function that is part of ISO/IEC + 10118-3:2004. It has a 512-bit message digest. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. + +MD5 +~~~~~~~ + +.. warning:: + + MD5 is a deprecated hash algorithm that has practical known collision + attacks. You are strongly discouraged from using it. + +.. class:: cryptography.primitives.hashes.MD5() + + MD5 is a deprecated cryptographic hash function. It has a 160-bit message + digest and has practical known collision attacks. + + .. method:: update(string) + + :param bytes string: The bytes you wish to hash. + + .. method:: digest() + + :return bytes: The message digest as bytes. + + .. method:: hexdigest() + + :return str: The message digest as hex. diff --git a/docs/primitives/index.rst b/docs/primitives/index.rst index 1066e30e..c18c62ca 100644 --- a/docs/primitives/index.rst +++ b/docs/primitives/index.rst @@ -4,4 +4,5 @@ Primitives .. toctree:: :maxdepth: 1 + cryptographic-hashes symmetric-encryption -- cgit v1.2.3 From 505491bd64dd410a3ac6c7f01c71e902a3c58917 Mon Sep 17 00:00:00 2001 From: Matthew Iversen Date: Sat, 19 Oct 2013 15:56:17 +1100 Subject: Simplify documentation --- docs/primitives/cryptographic-hashes.rst | 123 ++++++------------------------- 1 file changed, 24 insertions(+), 99 deletions(-) (limited to 'docs') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 1499f762..6e8f601b 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -1,23 +1,20 @@ Message Digests ==================== -SHA-1 -~~~~~~~ - -.. attention:: - - NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications - are strongly suggested to use SHA-2 over SHA-1. - -.. class:: cryptography.primitives.hashes.SHA1() +.. class:: cryptography.primitives.hashes.BaseHash - SHA-1 is a cryptographic hash function standardized by NIST. It has a - 160-bit message digest. + Abstract base class that implements a common interface for + all hash algorithms that follow here .. method:: update(string) :param bytes string: The bytes you wish to hash. + .. method:: copy() + + :return: a new instance of this object with a + copied internal state. + .. method:: digest() :return bytes: The message digest as bytes. @@ -26,120 +23,60 @@ SHA-1 :return str: The message digest as hex. +SHA-1 +~~~~~ -SHA-2 Family -~~~~~~~ - -.. class:: cryptography.primitives.hashes.SHA224() - - SHA-224 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 224-bit message digest. +.. attention:: - .. method:: update(string) + NIST has deprecated SHA-1 in favor of the SHA-2 variants. New applications + are strongly suggested to use SHA-2 over SHA-1. - :param bytes string: The bytes you wish to hash. +.. class:: cryptography.primitives.hashes.SHA1() - .. method:: digest() + SHA-1 is a cryptographic hash function standardized by NIST. It has a + 160-bit message digest. - :return bytes: The message digest as bytes. +SHA-2 Family +~~~~~~~~~~~~ - .. method:: hexdigest() +.. class:: cryptography.primitives.hashes.SHA224() - :return str: The message digest as hex. + SHA-224 is a cryptographic hash function from the SHA-2 family and + standardized by NIST. It has a 224-bit message digest. .. class:: cryptography.primitives.hashes.SHA256() SHA-256 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 256-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - .. class:: cryptography.primitives.hashes.SHA384() SHA-384 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 384-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - .. class:: cryptography.primitives.hashes.SHA512() SHA-512 is a cryptographic hash function from the SHA-2 family and standardized by NIST. It has a 512-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - RIPEMD160 -~~~~~~~ +~~~~~~~~~ .. class:: cryptography.primitives.hashes.RIPEMD160() RIPEMD160 is a cryptographic hash function that is part of ISO/IEC 10118-3:2004. It has a 160-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - Whirlpool -~~~~~~~ +~~~~~~~~~ .. class:: cryptography.primitives.hashes.Whirlpool() Whirlpool is a cryptographic hash function that is part of ISO/IEC 10118-3:2004. It has a 512-bit message digest. - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. - MD5 -~~~~~~~ +~~~ .. warning:: @@ -150,15 +87,3 @@ MD5 MD5 is a deprecated cryptographic hash function. It has a 160-bit message digest and has practical known collision attacks. - - .. method:: update(string) - - :param bytes string: The bytes you wish to hash. - - .. method:: digest() - - :return bytes: The message digest as bytes. - - .. method:: hexdigest() - - :return str: The message digest as hex. -- cgit v1.2.3 From 6b9ddeb015e3e36ba955c58191820ba1c07bdd76 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Sat, 19 Oct 2013 12:28:15 -0500 Subject: fix doc formatting and rename update param to "data" --- docs/primitives/cryptographic-hashes.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) (limited to 'docs') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 6e8f601b..397e50d7 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -3,17 +3,16 @@ Message Digests .. class:: cryptography.primitives.hashes.BaseHash - Abstract base class that implements a common interface for - all hash algorithms that follow here + Abstract base class that implements a common interface for all hash + algorithms that follow here. - .. method:: update(string) + .. method:: update(data) - :param bytes string: The bytes you wish to hash. + :param bytes data The bytes you wish to hash. .. method:: copy() - :return: a new instance of this object with a - copied internal state. + :return: a new instance of this object with a copied internal state. .. method:: digest() -- cgit v1.2.3 From ddc62f0d6546406b052a96eaa841ab8fd5335be8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 20 Oct 2013 06:14:24 -0700 Subject: Small fixups for the docs --- docs/primitives/cryptographic-hashes.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst index 397e50d7..d4dde042 100644 --- a/docs/primitives/cryptographic-hashes.rst +++ b/docs/primitives/cryptographic-hashes.rst @@ -1,5 +1,5 @@ Message Digests -==================== +=============== .. class:: cryptography.primitives.hashes.BaseHash @@ -8,7 +8,7 @@ Message Digests .. method:: update(data) - :param bytes data The bytes you wish to hash. + :param bytes data: The bytes you wish to hash. .. method:: copy() -- cgit v1.2.3