aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/community.rst2
-rw-r--r--docs/contributing.rst63
-rw-r--r--docs/index.rst1
-rw-r--r--docs/primitives/cryptographic-hashes.rst88
-rw-r--r--docs/primitives/index.rst1
-rw-r--r--docs/security.rst12
6 files changed, 159 insertions, 8 deletions
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/
diff --git a/docs/contributing.rst b/docs/contributing.rst
index 2d8fceeb..6a76c705 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``.
@@ -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 </security>`.
Code
----
@@ -50,6 +47,58 @@ 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);
+
+...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
+
+ // 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 *)
+
+Include a space after commas between parameters:
+
+.. code-block:: c
+
+ // Good
+ long f(int, char *)
+ // Bad
+ long f(int,char *)
+
+
Documentation
-------------
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/primitives/cryptographic-hashes.rst b/docs/primitives/cryptographic-hashes.rst
new file mode 100644
index 00000000..d4dde042
--- /dev/null
+++ b/docs/primitives/cryptographic-hashes.rst
@@ -0,0 +1,88 @@
+Message Digests
+===============
+
+.. class:: cryptography.primitives.hashes.BaseHash
+
+ Abstract base class that implements a common interface for all hash
+ algorithms that follow here.
+
+ .. method:: update(data)
+
+ :param bytes data: 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.
+
+ .. method:: hexdigest()
+
+ :return str: The message digest as hex.
+
+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.
+
+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.
+
+.. 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.
+
+.. 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.
+
+.. 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.
+
+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.
+
+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.
+
+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.
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
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.