aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/development/c-bindings.rst192
-rw-r--r--docs/development/index.rst1
-rw-r--r--docs/development/submitting-patches.rst66
-rw-r--r--docs/hazmat/primitives/asymmetric/dsa.rst67
-rw-r--r--docs/hazmat/primitives/interfaces.rst89
-rw-r--r--docs/spelling_wordlist.txt4
6 files changed, 315 insertions, 104 deletions
diff --git a/docs/development/c-bindings.rst b/docs/development/c-bindings.rst
new file mode 100644
index 00000000..56963379
--- /dev/null
+++ b/docs/development/c-bindings.rst
@@ -0,0 +1,192 @@
+C bindings
+==========
+
+C bindings are bindings to C libraries, using cffi_ whenever possible.
+
+.. _cffi: http://cffi.readthedocs.org
+
+Bindings live in :py:mod:`cryptography.hazmat.bindings`.
+
+Style guide
+-----------
+
+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;
+ ...;
+ };
+
+Include ``void`` if the function takes no arguments:
+
+.. code-block:: c
+
+ /* Good */
+ long f(void);
+ /* Bad */
+ long f();
+
+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 *)
+
+Use C-style ``/* */`` comments instead of C++-style ``//``:
+
+.. code-block:: c
+
+ // Bad
+ /* Good */
+
+Values set by ``#define`` should be assigned the appropriate type. If you see
+this:
+
+.. code-block:: c
+
+ #define SOME_INTEGER_LITERAL 0x0;
+ #define SOME_UNSIGNED_INTEGER_LITERAL 0x0001U;
+ #define SOME_STRING_LITERAL "hello";
+
+...it should be added to the bindings like so:
+
+.. code-block:: c
+
+ static const int SOME_INTEGER_LITERAL;
+ static const unsigned int SOME_UNSIGNED_INTEGER_LITERAL;
+ static const char *const SOME_STRING_LITERAL;
+
+Adding constant, types, functions...
+------------------------------------
+
+You can create bindings for any name that exists in some version of
+the library you're binding against. However, the project also has to
+keep supporting older versions of the library. In order to achieve
+this, binding modules have ``CUSTOMIZATIONS`` and
+``CONDITIONAL_NAMES`` constants.
+
+Let's say you want to enable quantum transmogrification. The upstream
+library implements this as the following API::
+
+ static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT;
+ static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT;
+ typedef ... QM_TRANSMOGRIFICATION_CTX;
+ int QM_transmogrify(QM_TRANSMOGRIFICATION_CTX *, int);
+
+To start, create a new constant that defines if the *actual* library
+has the feature you want, and add it to ``TYPES``::
+
+ static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION;
+
+This should start with ``Cryptography_``, since we're adding it in
+this library. This prevents namespace collisions.
+
+Then, define the actual features (constants, types, functions...) you
+want to expose. If it's a constant, just add it to ``TYPES``::
+
+ static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT;
+ static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT;
+
+If it's a struct, add it to ``TYPES`` as well. The following is an
+opaque struct::
+
+ typedef ... QM_TRANSMOGRIFICATION_CTX;
+
+... but you can also make some or all items in the struct accessible::
+
+ typedef struct {
+ /* Fundamental constant k for your particular universe */
+ BIGNUM *k;
+ ...;
+ } QM_TRANSMOGRIFICATION_CTX;
+
+Confusingly, functions that aren't always available on all supported
+versions of the library, should be defined in ``MACROS`` and *not* in
+``FUNCTIONS``. Fortunately, you just have to copy the signature::
+
+ int QM_transmogrify(QM_TRANSMOGRIFICATION_CTX *, int);
+
+Then, we define the ``CUSTOMIZATIONS`` entry. To do that, we have to
+come up with a C preprocessor expression that decides whether or not a
+feature exists in the library. For example::
+
+ #ifdef QM_transmogrify
+
+Then, we set the flag that signifies the feature exists::
+
+ static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION = 1;
+
+Otherwise, we set that flag to 0::
+
+ #else
+ static const long Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION = 0;
+
+Then, in that ``#else`` block, we define the names that aren't
+available as dummy values. For an integer constant, use 0::
+
+ static const int QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT = 0;
+ static const int QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT = 0;
+
+For a function, it's a bit trickier. You have to define a function
+pointer of the appropriate type to be NULL::
+
+ int (*QM_transmogrify)(QM_TRANSMOGRIFICATION_CTX *, int) = NULL;
+
+(To do that, copy the signature, put a ``*`` in front of the function
+name and wrap it in parentheses, and then put ``= NULL`` at the end).
+
+Note how types don't need to be conditionally defined, as long as all
+the necessarily type definitions are in place.
+
+Finally, add an entry to ``CONDITIONAL_NAMES`` with all of the things
+you want to conditionally export::
+
+ CONDITIONAL_NAMES = {
+ ...
+ "Cryptography_HAS_QUANTUM_TRANSMOGRIFICATION": [
+ "QM_TRANSMOGRIFICATION_ALIGNMENT_LEFT",
+ "QM_TRANSMOGRIFICATION_ALIGNMENT_RIGHT",
+ "QM_transmogrify"
+ ]
+ }
+
+Caveats
+~~~~~~~
+
+Sometimes, a set of loosely related features are added in the same
+version, and it's impractical to create ``#ifdef`` statements for each
+one. In that case, it may make sense to either check for a particular
+version. For example, to check for OpenSSL 1.0.0 or newer::
+
+ #if OPENSSL_VERSION_NUMBER >= 0x10000000L
+
+Sometimes, the version of a library on a particular platform will have
+features that you thought it wouldn't, based on its version.
+Occasionally, packagers appear to ship arbitrary VCS checkouts. As a
+result, sometimes you may have to add separate ``#ifdef`` statements
+for particular features. This kind of issue is typically only caught
+by running the tests on a wide variety of systems, which is the job of
+our continuous integration infrastructure.
diff --git a/docs/development/index.rst b/docs/development/index.rst
index 50b60900..f9bc9eea 100644
--- a/docs/development/index.rst
+++ b/docs/development/index.rst
@@ -14,6 +14,7 @@ bug check out `what to put in your bug report`_.
submitting-patches
reviewing-patches
test-vectors
+ c-bindings
.. _`GitHub`: https://github.com/pyca/cryptography
.. _`what to put in your bug report`: http://www.contribution-guide.org/#what-to-put-in-your-bug-report
diff --git a/docs/development/submitting-patches.rst b/docs/development/submitting-patches.rst
index b7f43283..fe2df431 100644
--- a/docs/development/submitting-patches.rst
+++ b/docs/development/submitting-patches.rst
@@ -75,70 +75,8 @@ specifying a different backend.
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;
- ...;
- };
-
-Include ``void`` if the function takes no arguments:
-
-.. code-block:: c
-
- // Good
- long f(void);
- // Bad
- long f();
-
-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 *)
-
-Values set by ``#define`` should be assigned the appropriate type. If you see
-this:
-
-.. code-block:: c
-
- #define SOME_INTEGER_LITERAL 0x0;
- #define SOME_UNSIGNED_INTEGER_LITERAL 0x0001U;
- #define SOME_STRING_LITERAL "hello";
-
-...it should be added to the bindings like so:
-
-.. code-block:: c
-
- static const int SOME_INTEGER_LITERAL;
- static const unsigned int SOME_UNSIGNED_INTEGER_LITERAL;
- static const char *const SOME_STRING_LITERAL;
+More information on C bindings can be found in :doc:`the dedicated
+section of the documentation <c-bindings>`.
Tests
-----
diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst
index 6848d84c..2167e528 100644
--- a/docs/hazmat/primitives/asymmetric/dsa.rst
+++ b/docs/hazmat/primitives/asymmetric/dsa.rst
@@ -210,6 +210,73 @@ DSA
:returns:
:class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext`
+.. class:: DSAParameterNumbers(p, q, g)
+
+ .. versionadded:: 0.5
+
+ The collection of integers that make up a set of DSA parameters.
+
+ .. attribute:: p
+
+ :type: int
+
+ The public modulus.
+
+ .. attribute:: q
+
+ :type: int
+
+ The sub-group order.
+
+ .. attribute:: g
+
+ :type: int
+
+ The generator.
+
+.. class:: DSAPublicNumbers(y, parameter_numbers)
+
+ .. versionadded:: 0.5
+
+ The collection of integers that make up a DSA public key.
+
+ .. attribute:: y
+
+ :type: int
+
+ The public value ``y``.
+
+ .. attribute:: parameter_numbers
+
+ :type: :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers`
+
+ The :class:`~cryptography.hazmat.primitives.dsa.DSAParameterNumbers`
+ associated with the public key.
+
+.. class:: DSAPrivateNumbers(x, public_numbers)
+
+ .. versionadded:: 0.5
+
+ The collection of integers that make up a DSA private key.
+
+ .. warning::
+
+ Revealing the value of ``x`` will compromise the security of any
+ cryptographic operations performed.
+
+ .. attribute:: x
+
+ :type: int
+
+ The private value ``x``.
+
+ .. attribute:: public_numbers
+
+ :type: :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers`
+
+ The :class:`~cryptography.hazmat.primitives.dsa.DSAPublicNumbers`
+ associated with the private key.
+
.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm
.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography
.. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf
diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst
index b8aca0c2..0c456326 100644
--- a/docs/hazmat/primitives/interfaces.rst
+++ b/docs/hazmat/primitives/interfaces.rst
@@ -13,7 +13,7 @@ to document argument and return types.
Symmetric ciphers
-~~~~~~~~~~~~~~~~~
+-----------------
.. currentmodule:: cryptography.hazmat.primitives.interfaces
@@ -48,7 +48,7 @@ Symmetric ciphers
Cipher modes
-------------
+~~~~~~~~~~~~
Interfaces used by the symmetric cipher modes described in
:ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`.
@@ -104,7 +104,44 @@ Interfaces used by the symmetric cipher modes described in
individual modes.
Asymmetric interfaces
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
+
+.. class:: AsymmetricSignatureContext
+
+ .. versionadded:: 0.2
+
+ .. method:: update(data)
+
+ :param bytes data: The data you want to sign.
+
+ .. method:: finalize()
+
+ :return bytes signature: The signature.
+
+
+.. class:: AsymmetricVerificationContext
+
+ .. versionadded:: 0.2
+
+ .. method:: update(data)
+
+ :param bytes data: The data you wish to verify using the signature.
+
+ .. method:: verify()
+
+ :raises cryptography.exceptions.InvalidSignature: If the signature does
+ not validate.
+
+
+.. class:: AsymmetricPadding
+
+ .. versionadded:: 0.2
+
+ .. attribute:: name
+
+
+RSA
+~~~
.. class:: RSAPrivateKey
@@ -236,6 +273,9 @@ Asymmetric interfaces
instance.
+DSA
+~~~
+
.. class:: DSAParameters
.. versionadded:: 0.3
@@ -458,6 +498,9 @@ Asymmetric interfaces
The bit length of the curve's base point.
+Elliptic Curve
+~~~~~~~~~~~~~~
+
.. class:: EllipticCurveSignatureAlgorithm
.. versionadded:: 0.5
@@ -526,42 +569,8 @@ Asymmetric interfaces
The elliptic curve for this key.
-.. class:: AsymmetricSignatureContext
-
- .. versionadded:: 0.2
-
- .. method:: update(data)
-
- :param bytes data: The data you want to sign.
-
- .. method:: finalize()
-
- :return bytes signature: The signature.
-
-
-.. class:: AsymmetricVerificationContext
-
- .. versionadded:: 0.2
-
- .. method:: update(data)
-
- :param bytes data: The data you wish to verify using the signature.
-
- .. method:: verify()
-
- :raises cryptography.exceptions.InvalidSignature: If the signature does
- not validate.
-
-
-.. class:: AsymmetricPadding
-
- .. versionadded:: 0.2
-
- .. attribute:: name
-
-
Hash algorithms
-~~~~~~~~~~~~~~~
+---------------
.. class:: HashAlgorithm
@@ -607,7 +616,7 @@ Hash algorithms
Key derivation functions
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
.. class:: KeyDerivationFunction
@@ -652,7 +661,7 @@ Key derivation functions
`CMAC`_
-~~~~~~~
+-------
.. class:: CMACContext
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index e7a63f26..dc123493 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -30,8 +30,12 @@ invariants
iOS
Koblitz
metadata
+namespace
+namespaces
pickleable
plaintext
+preprocessor
+preprocessors
pseudorandom
Schneier
scrypt
generated by cgit v1.2.3 (git 2.25.1) at 2025-04-04 17:38:22 +0000