From 90ae866e0a83ef92ce2b2e7c58ccb86e79f3bee8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 23 Dec 2013 17:21:00 -0600 Subject: add hmac_supported method to backend. Previously we were implicitly assuming that if a hash was supported then its hmac equivalent was as well. --- docs/hazmat/backends/interfaces.rst | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index b524943d..45fbaf09 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -126,12 +126,23 @@ A specific ``backend`` may provide one or more of these interfaces. A backend with methods for using cryptographic hash functions as message authentication codes. + .. method:: hmac_supported(algorithm) + + Check if the specified ``algorithm`` is supported by this backend. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: ``True`` if the specified ``algorithm`` is supported for HMAC + by this backend, otherwise ``False``. + .. method:: create_hmac_ctx(algorithm) Create a :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that - uses the specified ``algorithm`` to calculate a hash-based message - authentication code. + uses the specified ``algorithm`` to calculate a hash-based message + authentication code. :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` -- cgit v1.2.3 From 4f776c495cfef4dd29023cb7bb035612d1e53916 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 23 Dec 2013 17:25:54 -0600 Subject: fix erroneous indent and add abstractmethod to HMACBackend --- docs/hazmat/backends/interfaces.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 45fbaf09..5b6cd64d 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -141,8 +141,8 @@ A specific ``backend`` may provide one or more of these interfaces. Create a :class:`~cryptogrpahy.hazmat.primitives.interfaces.HashContext` that - uses the specified ``algorithm`` to calculate a hash-based message - authentication code. + uses the specified ``algorithm`` to calculate a hash-based message + authentication code. :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` -- cgit v1.2.3 From 1a9bbf24301a9b0dc76ede1128d74ca629075888 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 24 Dec 2013 10:59:50 -0800 Subject: Document our API stability policy. Fixes #312 --- docs/contributing.rst | 1 - docs/index.rst | 1 + 2 files changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/contributing.rst b/docs/contributing.rst index 744f2098..620e1b6a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -136,7 +136,6 @@ Include a space after commas between parameters: // Bad long f(int,char *) - Documentation ------------- diff --git a/docs/index.rst b/docs/index.rst index 381063df..70558bda 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -75,4 +75,5 @@ The ``cryptography`` open source project contributing security + api-stability community -- cgit v1.2.3 From f5415c859d4e413e9ac8b1862157babdcbda88ec Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 24 Dec 2013 11:00:15 -0800 Subject: Forgotten file --- docs/api-stability.rst | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 docs/api-stability.rst (limited to 'docs') diff --git a/docs/api-stability.rst b/docs/api-stability.rst new file mode 100644 index 00000000..6497a687 --- /dev/null +++ b/docs/api-stability.rst @@ -0,0 +1,48 @@ +API Stability +============= + +From its first release, ``cryptography`` will have a strong API stability +policy. + +What does this policy cover? +---------------------------- + +This policy includes any API or behavior which is documented in this +documentation. + +What does "stable" mean? +------------------------ + +* Public APIs will not be removed or renamed without providing a compatibility + alias. +* The behavior of existing APIs will not change. + +What doesn't this policy cover? +------------------------------- + +* We may add new features, things like the result of ``dir(obj))`` or the + contents of ``obj.__dict__`` may change. +* Objects are not guarnteed to be pickleable, and pickled objects from one + version of ``cryptography`` may not be loadable in future versions. + +Security +~~~~~~~~ + +In the event a security vulnerability, or hardening necessitates it, we will +break backwards compatibility in order to address an issue. + +Deprecation +----------- + +From time to time we will want to change the behavior of an API or remove it +entirely. In that case, here's how the process will work: + +* In ``cryptography X.Y`` the feature exists. +* In ``cryptography X.Y+1`` using that feature will emit a + ``PendingDeprecationWarning``. +* In ``cryptography X.Y+2`` using that feature will emit a + ``DeprecationWarning``. +* In ``cryptography X.Y+3`` the feature will be removed or changed. + +In short, code which runs without warnings will always continue to work for a +period of two releases. -- cgit v1.2.3 From 6cf1e697a8024c779b9b86d29f300a3bfed30cfe Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 24 Dec 2013 11:02:54 -0800 Subject: Note abotu development versions --- docs/api-stability.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/api-stability.rst b/docs/api-stability.rst index 6497a687..40608ac5 100644 --- a/docs/api-stability.rst +++ b/docs/api-stability.rst @@ -24,6 +24,8 @@ What doesn't this policy cover? contents of ``obj.__dict__`` may change. * Objects are not guarnteed to be pickleable, and pickled objects from one version of ``cryptography`` may not be loadable in future versions. +* Development versions of ``cryptography``. Before a feature is in a release, + it is not covered by this policy and may change. Security ~~~~~~~~ -- cgit v1.2.3 From d43134ae57a1bb91bfa47a53176a88789728d686 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 24 Dec 2013 11:03:16 -0800 Subject: Typo --- docs/api-stability.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/api-stability.rst b/docs/api-stability.rst index 40608ac5..a457306f 100644 --- a/docs/api-stability.rst +++ b/docs/api-stability.rst @@ -22,7 +22,7 @@ What doesn't this policy cover? * We may add new features, things like the result of ``dir(obj))`` or the contents of ``obj.__dict__`` may change. -* Objects are not guarnteed to be pickleable, and pickled objects from one +* Objects are not guaranteed to be pickleable, and pickled objects from one version of ``cryptography`` may not be loadable in future versions. * Development versions of ``cryptography``. Before a feature is in a release, it is not covered by this policy and may change. -- cgit v1.2.3 From 1c9e57bbc64d5023ec9d35f162b0a071a39b0a48 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 24 Dec 2013 12:47:45 -0800 Subject: Rephrase --- docs/api-stability.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/api-stability.rst b/docs/api-stability.rst index a457306f..e87cc140 100644 --- a/docs/api-stability.rst +++ b/docs/api-stability.rst @@ -30,8 +30,9 @@ What doesn't this policy cover? Security ~~~~~~~~ -In the event a security vulnerability, or hardening necessitates it, we will -break backwards compatibility in order to address an issue. +One exception to our API stability policy is for security. We will violate this +policy as necessary in order to resolve a security issue or harden +``cryptography`` against a possible attack. Deprecation ----------- -- cgit v1.2.3 From 8f42fe4e86267c4dee696707ac08371a1aa2531a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 24 Dec 2013 13:15:52 -0800 Subject: Slightly reorganize and cleanuip the backend docs --- docs/hazmat/backends/index.rst | 24 ++++++++++++------------ docs/hazmat/backends/openssl.rst | 4 ++-- 2 files changed, 14 insertions(+), 14 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst index a89cf0d5..06951281 100644 --- a/docs/hazmat/backends/index.rst +++ b/docs/hazmat/backends/index.rst @@ -1,17 +1,10 @@ .. hazmat:: -Bindings +Backends ======== -.. toctree:: - :maxdepth: 1 - - openssl - interfaces - - -Getting a Backend Provider -~~~~~~~~~~~~~~~~~~~~~~~~~~ +Getting a Backend +----------------- .. currentmodule:: cryptography.hazmat.backends @@ -19,8 +12,7 @@ Getting a Backend Provider the widest number of supported cryptographic algorithms as well as supporting platform specific implementations. -You can get the default backend by calling -:func:`~default_backend`. +You can get the default backend by calling :func:`~default_backend`. The default backend will change over time as we implement new backends and the libraries we use in those backends changes. @@ -32,3 +24,11 @@ the libraries we use in those backends changes. :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and :class:`~interfaces.HMACBackend`. +Individual Backends +------------------- + +.. toctree:: + :maxdepth: 1 + + openssl + interfaces diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 12fbff04..5e51c75e 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -1,7 +1,7 @@ .. hazmat:: -OpenSSL -======= +OpenSSL Backend +=============== These are `CFFI`_ bindings to the `OpenSSL`_ C library. -- cgit v1.2.3