diff options
Diffstat (limited to 'sites/www')
| -rw-r--r-- | sites/www/changelog.rst | 34 | ||||
| -rw-r--r-- | sites/www/index.rst | 5 | ||||
| -rw-r--r-- | sites/www/installing-1.x.rst | 120 | ||||
| -rw-r--r-- | sites/www/installing.rst | 136 |
4 files changed, 207 insertions, 88 deletions
diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 9a37c7b2..51238f32 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -12,6 +12,11 @@ Changelog network connectivity isn't timing out, but the remote server is otherwise unable to service the connection in a timely manner. Credit to ``@sanseihappa``. +* :bug:`742` (also re: :issue:`559`) Catch ``AssertionError`` thrown by + Cryptography when attempting to load bad ECDSA keys, turning it into an + ``SSHException``. This moves the behavior in line with other "bad keys" + situations, re: Paramiko's main auth loop. Thanks to MengHuan Yu for the + patch. * :bug:`789` Add a missing ``.closed`` attribute (plus ``._closed`` because reasons) to `ProxyCommand <paramiko.proxy.ProxyCommand>` so the earlier partial fix for :issue:`520` works in situations where one is gatewaying via @@ -40,6 +45,7 @@ Changelog * :support:`819 backported (>=1.15,<2.0)` Document how lacking ``gmp`` headers at install time can cause a significant performance hit if you build PyCrypto from source. (Most system-distributed packages already have this enabled.) +* :release:`2.0.2 <2016-07-25>` * :release:`1.17.2 <2016-07-25>` * :release:`1.16.3 <2016-07-25>` * :bug:`673 (1.16+)` (via :issue:`681`) Fix protocol banner read errors @@ -55,6 +61,7 @@ Changelog should address issues on Windows platforms that often result in errors like ``ArgumentError: [...] int too long to convert``. Thanks to ``@swohlerLL`` for the report and Jason R. Coombs for the patch. +* :release:`2.0.1 <2016-06-21>` * :release:`1.17.1 <2016-06-21>` * :release:`1.16.2 <2016-06-21>` * :bug:`520 (1.16+)` (Partial fix) Fix at least one instance of race condition @@ -67,9 +74,14 @@ Changelog <paramiko.channel.Channel.fileno>` after the channel has closed). Thanks to Przemysław Strzelczak for the report & reproduction case, and to Krzysztof Rusek for the fix. +* :release:`2.0.0 <2016-04-28>` * :release:`1.17.0 <2016-04-28>` * :release:`1.16.1 <2016-04-28>` * :release:`1.15.5 <2016-04-28>` +* :feature:`731` (working off the earlier :issue:`611`) Add support for 384- + and 512-bit elliptic curve groups in ECDSA key types (aka + ``ecdsa-sha2-nistp384`` / ``ecdsa-sha2-nistp521``). Thanks to Michiel Tiller + and ``@CrazyCasta`` for the patches. * :bug:`670` Due to an earlier bugfix, less-specific ``Host`` blocks' ``ProxyCommand`` values were overriding ``ProxyCommand none`` in more-specific ``Host`` blocks. This has been fixed in a backwards compatible @@ -81,6 +93,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..356fac49 --- /dev/null +++ b/sites/www/installing-1.x.rst @@ -0,0 +1,120 @@ +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. + +Slow vs fast crypto math +~~~~~~~~~~~~~~~~~~~~~~~~ + +PyCrypto attempts to use the ``gmp`` C math library if it is present on your +system, which enables what it internally calls "fastmath" (``_fastmath.so``). +When those headers are not available, it falls back to "slowmath" +(``_slowmath.py``) which is a pure-Python implementation. + +Real-world tests have shown significant benefits to using the C version of this +code; thus we strongly recommend you install the ``gmp`` development headers +**before** installing Paramiko/PyCrypto. E.g.:: + + $ apt-get install libgmp-dev # or just apt + $ yum install gmp-devel # or dnf + $ brew install gmp + +If you're unsure which version of math you've ended up with, a quick way to +check is to examine whether ``_fastmath.so`` or ``_slowmath.py`` appears in the +output of:: + + from Crypto.PublicKey import RSA + print(RSA._impl._math) + +Windows +~~~~~~~ + +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 f16369ff..6537b850 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 @@ -12,17 +19,15 @@ via `pip <http://pip-installer.org>`_:: $ pip install paramiko -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: @@ -33,97 +38,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 -======== +.. _cryptography: -`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 <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. -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. +In general, you'll need one of the following setups: -Slow vs fast crypto math -~~~~~~~~~~~~~~~~~~~~~~~~ +* 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. -PyCrypto attempts to use the ``gmp`` C math library if it is present on your -system, which enables what it internally calls "fastmath" (``_fastmath.so``). -When those headers are not available, it falls back to "slowmath" -(``_slowmath.py``) which is a pure-Python implementation. + .. 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. -Real-world tests have shown significant benefits to using the C version of this -code; thus we strongly recommend you install the ``gmp`` development headers -**before** installing Paramiko/PyCrypto. E.g.:: - - $ apt-get install libgmp-dev # or just apt - $ yum install gmp-devel # or dnf - $ brew install gmp - -If you're unsure which version of math you've ended up with, a quick way to -check is to examine whether ``_fastmath.so`` or ``_slowmath.py`` appears in the -output of:: - - from Crypto.PublicKey import RSA - print(RSA._impl._math) - -Windows -~~~~~~~ - -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:\> +.. _installation instructions: +.. _Cryptography's install docs: https://cryptography.io/en/latest/installation/ .. _gssapi: @@ -137,8 +97,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. @@ -152,3 +110,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 |