summaryrefslogtreecommitdiffhomepage
path: root/sites/www
diff options
context:
space:
mode:
Diffstat (limited to 'sites/www')
-rw-r--r--sites/www/changelog.rst22
-rw-r--r--sites/www/index.rst5
-rw-r--r--sites/www/installing-1.x.rst94
-rw-r--r--sites/www/installing.rst110
4 files changed, 169 insertions, 62 deletions
diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst
index c80885ed..e667e817 100644
--- a/sites/www/changelog.rst
+++ b/sites/www/changelog.rst
@@ -10,6 +10,28 @@ Changelog
erroneously non-optional ``file_size`` parameter. Should only affect users
who manually call ``prefetch``. Thanks to ``@stevevanhooser`` for catch &
patch.
+* :feature:`394` Replace PyCrypto with the Python Cryptographic Authority
+ (PyCA) 'Cryptography' library suite. This improves security, installability,
+ and performance; adds PyPy support; and much more.
+
+ There aren't enough ways to thank Alex Gaynor for all of his work on this,
+ and then his patience while the maintainer let his PR grow moss for a year
+ and change. Paul Kehrer came in with an assist, and I think I saw Olle
+ Lundberg, ``@techtonik`` and ``@johnthagen`` supplying backup as well. Thanks
+ to all!
+
+ .. warning::
+ **This is a backwards incompatible change.**
+
+ However, **it should only affect installation** requirements; **no API
+ changes are intended or expected**. Please report any such breakages as
+ bugs.
+
+ See our updated :doc:`installation docs <installing>` for details on what
+ is now required to install Paramiko; many/most users should be able to
+ simply ``pip install -U paramiko`` (especially if you **upgrade to pip
+ 8**).
+
* :bug:`577` (via :issue:`578`; should also fix :issue:`718`, :issue:`560`) Fix
stalled/hung SFTP downloads by cleaning up some threading lock issues. Thanks
to Stephen C. Pope for the patch.
diff --git a/sites/www/index.rst b/sites/www/index.rst
index 8e7562af..b09ab589 100644
--- a/sites/www/index.rst
+++ b/sites/www/index.rst
@@ -3,8 +3,9 @@ Welcome to Paramiko!
Paramiko is a Python (2.6+, 3.3+) implementation of the SSHv2 protocol [#]_,
providing both client and server functionality. While it leverages a Python C
-extension for low level cryptography (`PyCrypto <http://pycrypto.org>`_),
-Paramiko itself is a pure Python interface around SSH networking concepts.
+extension for low level cryptography
+(`Cryptography <https://cryptography.io>`_), Paramiko itself is a pure Python
+interface around SSH networking concepts.
This website covers project information for Paramiko such as the changelog,
contribution guidelines, development roadmap, news/blog, and so forth. Detailed
diff --git a/sites/www/installing-1.x.rst b/sites/www/installing-1.x.rst
new file mode 100644
index 00000000..0c2424bb
--- /dev/null
+++ b/sites/www/installing-1.x.rst
@@ -0,0 +1,94 @@
+Installing (1.x)
+================
+
+.. note:: Installing Paramiko 2.0 or above? See :doc:`installing` instead.
+
+This document includes legacy notes on installing Paramiko 1.x (specifically,
+1.13 and up). Users are strongly encouraged to upgrade to 2.0 when possible;
+PyCrypto (the dependency covered below) is no longer maintained and contains
+security vulnerabilities.
+
+General install notes
+=====================
+
+* Python 2.6+ and 3.3+ are supported; Python <=2.5 and 3.0-3.2 are **not
+ supported**.
+* See the note in the main install doc about :ref:`release-lines` for details
+ on specific versions you may want to install.
+
+ .. note:: 1.x will eventually be entirely end-of-lifed.
+* Paramiko 1.7-1.14 have only one dependency: :ref:`pycrypto`.
+* Paramiko 1.15+ (not including 2.x and above) add a second, pure-Python
+ dependency: the ``ecdsa`` module, trivially installable via PyPI.
+* Paramiko 1.15+ (again, not including 2.x and up) also allows you to
+ optionally install a few more dependencies to gain support for
+ :ref:`GSS-API/Kerberos <gssapi-on-1x>`.
+* Users on Windows may want to opt for the :ref:`pypm` approach.
+
+
+.. _pycrypto:
+
+PyCrypto
+========
+
+`PyCrypto <https://www.dlitz.net/software/pycrypto/>`__ provides the low-level
+(C-based) encryption algorithms we need to implement the SSH protocol. There
+are a couple gotchas associated with installing PyCrypto: its compatibility
+with Python's package tools, and the fact that it is a C-based extension.
+
+C extension
+-----------
+
+Unless you are installing from a precompiled source such as a Debian apt
+repository or RedHat RPM, or using :ref:`pypm <pypm>`, you will also need the
+ability to build Python C-based modules from source in order to install
+PyCrypto. Users on **Unix-based platforms** such as Ubuntu or Mac OS X will
+need the traditional C build toolchain installed (e.g. Developer Tools / XCode
+Tools on the Mac, or the ``build-essential`` package on Ubuntu or Debian Linux
+-- basically, anything with ``gcc``, ``make`` and so forth) as well as the
+Python development libraries, often named ``python-dev`` or similar.
+
+For **Windows** users we recommend using :ref:`pypm`, installing a C
+development environment such as `Cygwin <http://cygwin.com>`_ or obtaining a
+precompiled Win32 PyCrypto package from `voidspace's Python modules page
+<http://www.voidspace.org.uk/python/modules.shtml#pycrypto>`_.
+
+.. note::
+ Some Windows users whose Python is 64-bit have found that the PyCrypto
+ dependency ``winrandom`` may not install properly, leading to ImportErrors.
+ In this scenario, you'll probably need to compile ``winrandom`` yourself
+ via e.g. MS Visual Studio. See `Fabric #194
+ <https://github.com/fabric/fabric/issues/194>`_ for info.
+
+
+.. _pypm:
+
+ActivePython and PyPM
+=====================
+
+Windows users who already have ActiveState's `ActivePython
+<http://www.activestate.com/activepython/downloads>`_ distribution installed
+may find Paramiko is best installed with `its package manager, PyPM
+<http://code.activestate.com/pypm/>`_. Below is example output from an
+installation of Paramiko via ``pypm``::
+
+ C:\> pypm install paramiko
+ The following packages will be installed into "%APPDATA%\Python" (2.7):
+ paramiko-1.7.8 pycrypto-2.4
+ Get: [pypm-free.activestate.com] paramiko 1.7.8
+ Get: [pypm-free.activestate.com] pycrypto 2.4
+ Installing paramiko-1.7.8
+ Installing pycrypto-2.4
+ C:\>
+
+
+.. _gssapi-on-1x:
+
+Optional dependencies for GSS-API / SSPI / Kerberos
+===================================================
+
+First, see the main install doc's notes: :ref:`gssapi` - everything there is
+required for Paramiko 1.x as well.
+
+Additionally, users of Paramiko 1.x, on all platforms, need a final dependency:
+`pyasn1 <https://pypi.python.org/pypi/pyasn1>`_ ``0.1.7`` or better.
diff --git a/sites/www/installing.rst b/sites/www/installing.rst
index a657c3fc..5a41a76b 100644
--- a/sites/www/installing.rst
+++ b/sites/www/installing.rst
@@ -2,6 +2,13 @@
Installing
==========
+
+.. note::
+ These instructions cover Paramiko 2.0 and above. If you're looking to
+ install Paramiko 1.x, see :doc:`installing-1.x`. However, **the 1.x line
+ relies on insecure dependencies** so upgrading is strongly encouraged.
+
+
.. _paramiko-itself:
Paramiko itself
@@ -16,17 +23,15 @@ via `pip <http://pip-installer.org>`_::
Users who want the bleeding edge can install the development version via
``pip install paramiko==dev``.
-We currently support **Python 2.6, 2.7 and 3.3+** (Python **3.2** should also
-work but has a less-strong compatibility guarantee from us.) Users on Python
-2.5 or older are urged to upgrade.
+We currently support **Python 2.6, 2.7, 3.3+, and PyPy**. Users on Python 2.5
+or older (or 3.2 or older) are urged to upgrade.
-Paramiko has two hard dependencies: the pure-Python ECDSA module ``ecdsa``, and the
-PyCrypto C extension. ``ecdsa`` is easily installable from wherever you
-obtained Paramiko's package; PyCrypto may require more work. Read on for
-details.
+Paramiko has only one direct hard dependency: the Cryptography library. See
+:ref:`cryptography`.
If you need GSS-API / SSPI support, see :ref:`the below subsection on it
-<gssapi>` for details on additional dependencies.
+<gssapi>` for details on its optional dependencies.
+
.. _release-lines:
@@ -37,71 +42,52 @@ Users desiring stability may wish to pin themselves to a specific release line
once they first start using Paramiko; to assist in this, we guarantee bugfixes
for the last 2-3 releases including the latest stable one.
-If you're unsure which version to install, we have suggestions:
+This typically spans major & minor versions, so even if e.g. 3.1 is the latest
+stable release, it's likely that bugfixes will occasionally come out for the
+latest 2.x and perhaps even 1.x releases, as well as for 3.0. New feature
+releases for previous major-version lines are less likely but not unheard of.
+
+If you're unsure which version to install:
* **Completely new users** should always default to the **latest stable
release** (as above, whatever is newest / whatever shows up with ``pip
install paramiko``.)
-* **Users upgrading from a much older version** (e.g. the 1.7.x line) should
- probably get the **oldest actively supported line** (see the paragraph above
- this list for what that currently is.)
+* **Users upgrading from a much older version** (e.g. 1.7.x through 1.10.x)
+ should probably get the **oldest actively supported line** (check the
+ :doc:`changelog` for recent releases).
* **Everybody else** is hopefully already "on" a given version and can
carefully upgrade to whichever version they care to, when their release line
stops being supported.
-PyCrypto
-========
-
-`PyCrypto <https://www.dlitz.net/software/pycrypto/>`_ provides the low-level
-(C-based) encryption algorithms we need to implement the SSH protocol. There
-are a couple gotchas associated with installing PyCrypto: its compatibility
-with Python's package tools, and the fact that it is a C-based extension.
+.. _cryptography:
-C extension
------------
+Cryptography
+============
-Unless you are installing from a precompiled source such as a Debian apt
-repository or RedHat RPM, or using :ref:`pypm <pypm>`, you will also need the
-ability to build Python C-based modules from source in order to install
-PyCrypto. Users on **Unix-based platforms** such as Ubuntu or Mac OS X will
-need the traditional C build toolchain installed (e.g. Developer Tools / XCode
-Tools on the Mac, or the ``build-essential`` package on Ubuntu or Debian Linux
--- basically, anything with ``gcc``, ``make`` and so forth) as well as the
-Python development libraries, often named ``python-dev`` or similar.
+`Cryptography <https://cryptography.io>`__ provides the low-level (C-based)
+encryption algorithms we need to implement the SSH protocol. It has detailed
+`installation instructions`_ (and an `FAQ
+<https://cryptography.io/en/latest/faq/>`_) which you should read carefully.
-For **Windows** users we recommend using :ref:`pypm`, installing a C
-development environment such as `Cygwin <http://cygwin.com>`_ or obtaining a
-precompiled Win32 PyCrypto package from `voidspace's Python modules page
-<http://www.voidspace.org.uk/python/modules.shtml#pycrypto>`_.
+In general, you'll need one of the following setups:
-.. note::
- Some Windows users whose Python is 64-bit have found that the PyCrypto
- dependency ``winrandom`` may not install properly, leading to ImportErrors.
- In this scenario, you'll probably need to compile ``winrandom`` yourself
- via e.g. MS Visual Studio. See `Fabric #194
- <https://github.com/fabric/fabric/issues/194>`_ for info.
-
-
-.. _pypm:
-
-ActivePython and PyPM
-=====================
+* On Windows or Mac OS X, provided your ``pip`` is modern (8.x+): nothing else
+ is required. ``pip`` will install statically compiled binary archives of
+ Cryptography & its dependencies.
+* On Linux, or on other platforms with older versions of ``pip``: you'll need a
+ C build toolchain, plus development headers for Python, OpenSSL and
+ ``libffi``. Again, see `Cryptography's install docs`_; these requirements may
+ occasionally change.
-Windows users who already have ActiveState's `ActivePython
-<http://www.activestate.com/activepython/downloads>`_ distribution installed
-may find Paramiko is best installed with `its package manager, PyPM
-<http://code.activestate.com/pypm/>`_. Below is example output from an
-installation of Paramiko via ``pypm``::
+ .. warning::
+ If you go this route, note that **OpenSSL 1.0.1 or newer is effectively
+ required**. Cryptography 1.3 and older technically allow OpenSSL 0.9.8, but
+ 1.4 and newer - which Paramiko will gladly install or upgrade, if you e.g.
+ ``pip install -U`` - drop that support.
- C:\> pypm install paramiko
- The following packages will be installed into "%APPDATA%\Python" (2.7):
- paramiko-1.7.8 pycrypto-2.4
- Get: [pypm-free.activestate.com] paramiko 1.7.8
- Get: [pypm-free.activestate.com] pycrypto 2.4
- Installing paramiko-1.7.8
- Installing pycrypto-2.4
- C:\>
+.. _installation instructions:
+.. _Cryptography's install docs: https://cryptography.io/en/latest/installation/
.. _gssapi:
@@ -115,8 +101,6 @@ due to their infrequent utility & non-platform-agnostic requirements):
* It hopefully goes without saying but **all platforms** need **a working
installation of GSS-API itself**, e.g. Heimdal.
-* **All platforms** need `pyasn1 <https://pypi.python.org/pypi/pyasn1>`_
- ``0.1.7`` or better.
* **Unix** needs `python-gssapi <https://pypi.python.org/pypi/python-gssapi/>`_
``0.6.1`` or better.
@@ -130,3 +114,9 @@ due to their infrequent utility & non-platform-agnostic requirements):
delegation, make sure that the target host is trusted for delegation in the
active directory configuration. For details see:
http://technet.microsoft.com/en-us/library/cc738491%28v=ws.10%29.aspx
+
+
+.. toctree::
+ :hidden:
+
+ installing-1.x