diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/development/c-bindings.rst | 192 | ||||
| -rw-r--r-- | docs/development/index.rst | 1 | ||||
| -rw-r--r-- | docs/development/submitting-patches.rst | 66 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 47 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 67 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 24 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 164 | ||||
| -rw-r--r-- | docs/spelling_wordlist.txt | 6 |
8 files changed, 442 insertions, 125 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/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 1a2603bc..5cbd47d1 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -215,6 +215,8 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_rsa_signature_ctx(private_key, padding, algorithm) + .. deprecated:: 0.5 + :param private_key: An instance of an :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` provider. @@ -232,6 +234,8 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_rsa_verification_ctx(public_key, signature, padding, algorithm) + .. deprecated:: 0.5 + :param public_key: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` provider. @@ -251,10 +255,13 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: mgf1_hash_supported(algorithm) + ..deprecated:: 0.5 + Check if the specified ``algorithm`` is supported for use with :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` inside :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` - padding. + padding. This method is deprecated in favor of + ``rsa_padding_supported``. :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` @@ -285,6 +292,8 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: decrypt_rsa(private_key, ciphertext, padding) + .. deprecated:: 0.5 + :param private_key: An instance of an :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` provider. @@ -305,6 +314,8 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: encrypt_rsa(public_key, plaintext, padding) + .. deprecated:: 0.5 + :param public_key: An instance of an :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` provider. @@ -459,6 +470,40 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: ``True`` if the given values of ``p``, ``q``, and ``g`` are supported by this backend, otherwise ``False``. + .. method:: load_dsa_parameter_numbers(numbers): + + :param numbers: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers`. + + :returns: A provider of + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters`. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This raised when + any backend specific criteria are not met. + + .. method:: load_dsa_private_numbers(numbers): + + :param numbers: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers`. + + :returns: A provider of + :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey`. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This raised when + any backend specific criteria are not met. + + .. method:: load_dsa_public_numbers(numbers): + + :param numbers: An instance of + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers`. + + :returns: A provider of + :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey`. + + :raises cryptography.exceptions.UnsupportedAlgorithm: This raised when + any backend specific criteria are not met. + + .. class:: CMACBackend 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/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 71b7cd9c..c3962901 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -385,6 +385,18 @@ RSA The collection of integers that make up an RSA public key. + .. method:: public_key(backend) + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :return: A :class:`~cryptography.hazmat.primitives.interfaces.RSAPublicKey` + provider. + + :raises UnsupportedAlgorithm: If the given backend does not support + loading numbers. + .. attribute:: n :type: int @@ -411,6 +423,18 @@ RSA secret. Revealing them will compromise the security of any cryptographic operations performed with a key loaded from them. + .. method:: private_key(backend) + + :param backend: A + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + provider. + + :return: A :class:`~cryptography.hazmat.primitives.interfaces.RSAPrivateKey` + provider. + + :raises UnsupportedAlgorithm: If the given backend does not support + loading numbers. + .. attribute:: public_numbers :type: :class:`~cryptography.hazmat.primitives.rsa.RSAPublicNumbers` diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 1e0ada18..755cef41 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 @@ -112,7 +149,7 @@ Asymmetric interfaces An `RSA`_ private key. - .. method:: signer(padding, algorithm, backend) + .. method:: signer(padding, algorithm) .. versionadded:: 0.3 @@ -126,14 +163,10 @@ Asymmetric interfaces :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` - .. method:: decrypt(ciphertext, padding, backend) + .. method:: decrypt(ciphertext, padding) .. versionadded:: 0.4 @@ -145,10 +178,6 @@ Asymmetric interfaces :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - :return bytes: Decrypted data. .. method:: public_key() @@ -186,7 +215,7 @@ Asymmetric interfaces An `RSA`_ public key. - .. method:: verifier(signature, padding, algorithm, backend) + .. method:: verifier(signature, padding, algorithm) .. versionadded:: 0.3 @@ -203,14 +232,10 @@ Asymmetric interfaces :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` - .. method:: encrypt(plaintext, padding, backend) + .. method:: encrypt(plaintext, padding) .. versionadded:: 0.4 @@ -222,10 +247,6 @@ Asymmetric interfaces :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. - :param backend: A - :class:`~cryptography.hazmat.backends.interfaces.RSABackend` - provider. - :return bytes: Encrypted data. .. attribute:: key_size @@ -252,6 +273,9 @@ Asymmetric interfaces instance. +DSA +~~~ + .. class:: DSAParameters .. versionadded:: 0.3 @@ -259,6 +283,23 @@ Asymmetric interfaces `DSA`_ parameters. +.. class:: DSAParametersWithNumbers + + .. versionadded:: 0.5 + + Extends :class:`DSAParameters`. + + .. method:: parameter_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers` + object. + + :returns: A + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAParameterNumbers` + instance. + + .. class:: DSAPrivateKey .. versionadded:: 0.3 @@ -301,6 +342,23 @@ Asymmetric interfaces The bit length of the modulus. +.. class:: DSAPrivateKeyWithNumbers + + .. versionadded:: 0.5 + + Extends :class:`DSAPrivateKey`. + + .. method:: private_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers` + object. + + :returns: A + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPrivateNumbers` + instance. + + .. class:: DSAPublicKey .. versionadded:: 0.3 @@ -341,6 +399,23 @@ Asymmetric interfaces :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` +.. class:: DSAPublicKeyWithNumbers + + .. versionadded:: 0.5 + + Extends :class:`DSAPublicKey`. + + .. method:: private_numbers() + + Create a + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers` + object. + + :returns: A + :class:`~cryptography.hazmat.primitives.asymmetric.dsa.DSAPublicNumbers` + instance. + + .. class:: EllipticCurve .. versionadded:: 0.5 @@ -361,6 +436,9 @@ Asymmetric interfaces The bit length of the curve's base point. +Elliptic Curve +~~~~~~~~~~~~~~ + .. class:: EllipticCurveSignatureAlgorithm .. versionadded:: 0.5 @@ -429,42 +507,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 @@ -510,7 +554,7 @@ Hash algorithms Key derivation functions -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ .. class:: KeyDerivationFunction @@ -555,7 +599,7 @@ Key derivation functions `CMAC`_ -~~~~~~~ +------- .. class:: CMACContext diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index d5a2bee3..dc123493 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -13,6 +13,7 @@ conda crypto cryptographic cryptographically +Debian decrypt decrypted decrypting @@ -29,12 +30,17 @@ invariants iOS Koblitz metadata +namespace +namespaces pickleable plaintext +preprocessor +preprocessors pseudorandom Schneier scrypt testability +Ubuntu unencrypted unpadded unpadding |