From e68d73e37be57774246165a5d5263c89825e0864 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Tue, 31 Dec 2013 14:00:38 +0000 Subject: Document compiling OpenSSL to avoid conflicts --- docs/hazmat/backends/openssl.rst | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 5e51c75e..99b327d9 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -21,5 +21,32 @@ These are `CFFI`_ bindings to the `OpenSSL`_ C library. and access constants. +Using your own OpenSSL on Linux +------------------------------- + +Python links to OpenSSL for its own purposes and this can sometimes cause +problems when you wish to use a different version of OpenSSL with cryptography. +If you want to use cryptography with your own build of OpenSSL you will need to +make sure that the build is configured correctly so that your version of +OpenSSL doesn't conflict with Python's. + +The options you need to add allow the linker to identify every symbol correctly +even when multiple versions of the library are linked into the same program. If +you are using your distribution's source packages these will probably be +patched in for you already, otherwise you'll need to use options something like +this when configuring OpenSSL:: + + ./config -Wl,--version-script=openssl.ld -Wl,-Bsymbolic-functions -fPIC shared + +You'll also need to generate your own ``openssl.ld`` file. For example:: + + OPENSSL_1.0.1F_CUSTOM { + global: + *; + }; + +You should replace the version string on the first line as appropriate for your +build. + .. _`CFFI`: https://cffi.readthedocs.org/ .. _`OpenSSL`: https://www.openssl.org/ -- cgit v1.2.3 From dd1f5c5398a4c38179af70ed258641d720aa7d28 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 1 Jan 2014 06:23:31 -0800 Subject: Bump the copyright year --- docs/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/conf.py b/docs/conf.py index 5092e4d3..5dbcdab8 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -54,7 +54,7 @@ master_doc = 'index' # General information about the project. project = 'Cryptography' -copyright = '2013, Individual Contributors' +copyright = '2013-2014, Individual Contributors' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the -- cgit v1.2.3 From 77762bcb2fae77de60d37c60f74874730eeb785b Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 1 Jan 2014 07:53:48 -0800 Subject: This page has been subsumed by the index --- docs/architecture.rst | 13 ------------- docs/index.rst | 5 +++-- 2 files changed, 3 insertions(+), 15 deletions(-) delete mode 100644 docs/architecture.rst (limited to 'docs') diff --git a/docs/architecture.rst b/docs/architecture.rst deleted file mode 100644 index bacde1bb..00000000 --- a/docs/architecture.rst +++ /dev/null @@ -1,13 +0,0 @@ -Architecture -============ - -``cryptography`` has three different layers: - -* ``cryptography``: This package contains higher level recipes, for example - "encrypt and then MAC". This is implemented on top of - ``cryptography.hazmat.primitives``. -* ``cryptography.hazmat.primitives``: This packages contains low level - algorithms, things like ``AES`` or ``SHA1``. This is implemented on top of - ``cryptography.hazmat.backends``. -* ``cryptography.hazmat.backends``: This package contains bindings to low level - cryptographic libraries. Our initial target is OpenSSL. diff --git a/docs/index.rst b/docs/index.rst index 70558bda..81e48dd8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,7 +43,9 @@ The other level is low-level cryptographic primitives. These are often dangerous and can be used incorrectly. They require making decisions and having an in-depth knowledge of the cryptographic concepts at work. Because of the potential danger in working at this level, this is referred to as the -"hazardous materials" or "hazmat" layer. +"hazardous materials" or "hazmat" layer. These live in the +``cryptography.hazmat`` package, and their documentation will always contain a +admonition at the top. We recommend using the recipes layer whenever possible, and falling back to the hazmat layer only when necessary. @@ -54,7 +56,6 @@ The recipes layer .. toctree:: :maxdepth: 2 - architecture exceptions glossary -- cgit v1.2.3 From d8614a298d3f01786535fb966b02b7bfc22a8a0c Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 1 Jan 2014 08:22:40 -0800 Subject: Typo fix --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs') diff --git a/docs/index.rst b/docs/index.rst index 81e48dd8..9939182f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -44,7 +44,7 @@ dangerous and can be used incorrectly. They require making decisions and having an in-depth knowledge of the cryptographic concepts at work. Because of the potential danger in working at this level, this is referred to as the "hazardous materials" or "hazmat" layer. These live in the -``cryptography.hazmat`` package, and their documentation will always contain a +``cryptography.hazmat`` package, and their documentation will always contain an admonition at the top. We recommend using the recipes layer whenever possible, and falling back to the -- cgit v1.2.3 From c368ac2edfa21a6686ccd613fe0b889feb05d421 Mon Sep 17 00:00:00 2001 From: Alex Stapleton Date: Tue, 31 Dec 2013 13:43:38 +0000 Subject: Split OpenSSL binding --- docs/hazmat/backends/openssl.rst | 17 ++--------------- docs/hazmat/bindings/index.rst | 22 ++++++++++++++++++++++ docs/hazmat/bindings/openssl.rst | 27 +++++++++++++++++++++++++++ docs/index.rst | 1 + 4 files changed, 52 insertions(+), 15 deletions(-) create mode 100644 docs/hazmat/bindings/index.rst create mode 100644 docs/hazmat/bindings/openssl.rst (limited to 'docs') diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 99b327d9..404573a3 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -3,23 +3,11 @@ OpenSSL Backend =============== -These are `CFFI`_ bindings to the `OpenSSL`_ C library. +The `OpenSSL`_ C library. .. data:: cryptography.hazmat.backends.openssl.backend - This is the exposed API for the OpenSSL bindings. It has two public - attributes: - - .. attribute:: ffi - - This is a :class:`cffi.FFI` instance. It can be used to allocate and - otherwise manipulate OpenSSL structures. - - .. attribute:: lib - - This is a ``cffi`` library. It can be used to call OpenSSL functions, - and access constants. - + This is the exposed API for the OpenSSL backend. It has no public attributes. Using your own OpenSSL on Linux ------------------------------- @@ -48,5 +36,4 @@ You'll also need to generate your own ``openssl.ld`` file. For example:: You should replace the version string on the first line as appropriate for your build. -.. _`CFFI`: https://cffi.readthedocs.org/ .. _`OpenSSL`: https://www.openssl.org/ diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst new file mode 100644 index 00000000..809eddfc --- /dev/null +++ b/docs/hazmat/bindings/index.rst @@ -0,0 +1,22 @@ +.. hazmat:: + +Bindings +======== + +.. currentmodule:: cryptography.hazmat.bindings + +``cryptography`` aims to provide low-level CFFI based bindings to multiple +native C libraries. These provide no automatic initialisation of the library +and may not provide complete wrappers for its API. + +Using these functions directly is likely to require you to be careful in +managing memory allocation, locking and other resources. + + +Individual Bindings +------------------- + +.. toctree:: + :maxdepth: 1 + + openssl diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst new file mode 100644 index 00000000..373fe472 --- /dev/null +++ b/docs/hazmat/bindings/openssl.rst @@ -0,0 +1,27 @@ +.. hazmat:: + +OpenSSL Binding +=============== + +.. currentmodule:: cryptography.hazmat.bindings.openssl.binding + +These are `CFFI`_ bindings to the `OpenSSL`_ C library. + +.. class:: cryptography.hazmat.bindings.openssl.binding.Binding() + + This is the exposed API for the OpenSSL bindings. It has two public + attributes: + + .. attribute:: ffi + + This is a :class:`cffi.FFI` instance. It can be used to allocate and + otherwise manipulate OpenSSL structures. + + .. attribute:: lib + + This is a ``cffi`` library. It can be used to call OpenSSL functions, + and access constants. + + +.. _`CFFI`: https://cffi.readthedocs.org/ +.. _`OpenSSL`: https://www.openssl.org/ diff --git a/docs/index.rst b/docs/index.rst index 9939182f..5eb3de7d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -67,6 +67,7 @@ The hazardous materials layer hazmat/primitives/index hazmat/backends/index + hazmat/bindings/index The ``cryptography`` open source project ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- cgit v1.2.3