From b42ff32f3dfb097ef06fdc7189b4889c92360a77 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 16 Sep 2014 10:38:20 -0700 Subject: Try to update the installation docs --- sites/www/installing.rst | 73 +++++++++++++----------------------------------- 1 file changed, 20 insertions(+), 53 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 5528b28a..764c0a13 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -16,13 +16,13 @@ via `pip `_:: 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** (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. -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 +Paramiko has two hard dependencies: the pure-Python ECDSA module ``ecdsa``, and +the Cryptography library. ``ecdsa`` is easily installable from wherever you +obtained Paramiko's package; Cryptography may require more work. Read on for details. If you need GSS-API / SSPI support, see :ref:`the below subsection on it @@ -50,61 +50,28 @@ If you're unsure which version to install, we have suggestions: stops being supported. -PyCrypto -======== +Cryptography +============ -`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 `_ provides the low-level (C-based) +encryption algorithms we need to implement the SSH protocol. There are a few +things to be aware of when installing Cryptography, because it includes a +C-extension. C extension ----------- -Unless you are installing from a precompiled source such as a Debian apt -repository or RedHat RPM, or using :ref:`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 +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. +Python development libraries, often named ``python-dev`` or similar, and libffi +development libraries, often named ``libffi-dev``. -For **Windows** users we recommend using :ref:`pypm`, installing a C -development environment such as `Cygwin `_ or obtaining a -precompiled Win32 PyCrypto package from `voidspace's Python modules page -`_. +For **Windows** users we recommend using the most recent version of ``pip``, +Cryptography has binary wheels on PyPI, which remove the need for having a C +compiler. -.. 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 - `_ for info. - - -.. _pypm: - -ActivePython and PyPM -===================== - -Windows users who already have ActiveState's `ActivePython -`_ distribution installed -may find Paramiko is best installed with `its package manager, 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: Optional dependencies for GSS-API / SSPI / Kerberos =================================================== -- cgit v1.2.3 From f29770490c2b4df1937483c5cb6dbc05ed98992f Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 18 Sep 2014 18:04:40 -0700 Subject: Note OPenSSL headers as well --- sites/www/installing.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 507fe2fa..f7dd8594 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -65,8 +65,9 @@ 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, and libffi -development libraries, often named ``libffi-dev``. +Python development libraries, often named ``python-dev`` or similar, OpenSSL +headers, often named ``libssl-dev``, and libffi development libraries, often +named ``libffi-dev``. For **Windows** users we recommend using the most recent version of ``pip``, Cryptography has binary wheels on PyPI, which remove the need for having a C -- cgit v1.2.3 From 18bc966c3d3390d85c194a42be5921516d93e296 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 18 Sep 2014 18:23:31 -0700 Subject: Add back intro sentence --- sites/www/installing.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index f7dd8594..d6edbd5a 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -61,13 +61,15 @@ C-extension. C extension ----------- -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, OpenSSL -headers, often named ``libssl-dev``, and libffi development libraries, often -named ``libffi-dev``. +Unless you are installing from a precompiled source such as a Debian apt +repository or RedHat RPM,, you will also need the ability to build Python +C-based modules from source in order to install Cryptography. 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, OpenSSL headers, often named +``libssl-dev``, and libffi development libraries, often named ``libffi-dev``. For **Windows** users we recommend using the most recent version of ``pip``, Cryptography has binary wheels on PyPI, which remove the need for having a C -- cgit v1.2.3 From d563ba28291fa1f966353c5ef7e4c32680aa93e8 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 18 Sep 2014 18:25:40 -0700 Subject: Document that pyasn1 is required --- paramiko/ssh_gss.py | 18 ++---------------- setup.py | 2 +- sites/www/installing.rst | 10 ++++------ tox-requirements.txt | 2 +- 4 files changed, 8 insertions(+), 24 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/paramiko/ssh_gss.py b/paramiko/ssh_gss.py index ebf2cc80..dfc9ddc8 100644 --- a/paramiko/ssh_gss.py +++ b/paramiko/ssh_gss.py @@ -39,22 +39,8 @@ import sys """ GSS_AUTH_AVAILABLE = True -try: - from pyasn1.type.univ import ObjectIdentifier - from pyasn1.codec.der import encoder, decoder -except ImportError: - GSS_AUTH_AVAILABLE = False - class ObjectIdentifier(object): - def __init__(self, *args): - raise NotImplementedError("Module pyasn1 not importable") - - class decoder(object): - def decode(self): - raise NotImplementedError("Module pyasn1 not importable") - - class encoder(object): - def encode(self): - raise NotImplementedError("Module pyasn1 not importable") +from pyasn1.type.univ import ObjectIdentifier +from pyasn1.codec.der import encoder, decoder from paramiko.common import MSG_USERAUTH_REQUEST from paramiko.ssh_exception import SSHException diff --git a/setup.py b/setup.py index 91e9640c..05933c03 100644 --- a/setup.py +++ b/setup.py @@ -43,7 +43,7 @@ try: 'install_requires': [ 'cryptography >= 0.5.4', 'ecdsa >= 0.11', - 'pyasn1', + 'pyasn1 >= 0.1.7', ], } except ImportError: diff --git a/sites/www/installing.rst b/sites/www/installing.rst index d6edbd5a..dc20590e 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -20,10 +20,10 @@ We currently support **Python 2.6, 2.7, 3.3+, and PyPy** (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. -Paramiko has two hard dependencies: the pure-Python ECDSA module ``ecdsa``, and -the Cryptography library. ``ecdsa`` is easily installable from wherever you -obtained Paramiko's package; Cryptography may require more work. Read on for -details. +Paramiko has three hard dependencies: the pure-Python ECDSA module ``ecdsa`` +and ASN1 module ``pyasn1``, and the Cryptography library. ``ecdsa`` is easily +installable from wherever you obtained Paramiko's package; Cryptography may +require more work. Read on for details. If you need GSS-API / SSPI support, see :ref:`the below subsection on it ` for details on additional dependencies. @@ -85,8 +85,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 `_ - ``0.1.7`` or better. * **Unix** needs `python-gssapi `_ ``0.6.1`` or better. diff --git a/tox-requirements.txt b/tox-requirements.txt index 3a834b7f..e66a4534 100644 --- a/tox-requirements.txt +++ b/tox-requirements.txt @@ -1,3 +1,3 @@ # Not sure why tox can't just read setup.py? cryptography >= 0.5.4 -pyasn1 +pyasn1 >= 0.1.7 -- cgit v1.2.3 From 5130ad1f755ce0939ad51d88720a9b90fd8b3c00 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sun, 15 Mar 2015 13:10:35 -0400 Subject: Update for cryptography 0.8 and general cleanups --- README | 2 +- paramiko/dsskey.py | 4 +-- paramiko/ecdsakey.py | 70 ++++-------------------------------------------- setup.py | 2 +- sites/www/installing.rst | 6 ++--- tox-requirements.txt | 2 +- 6 files changed, 12 insertions(+), 74 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/README b/README index 7e848aca..36d7055f 100644 --- a/README +++ b/README @@ -36,7 +36,7 @@ Requirements - Python 2.6 or better - this includes Python 3.2 and higher as well. - - Cryptography 0.7 or better + - Cryptography 0.8 or better - pyasn1 0.1.7 or better If you have setuptools, you can build and install paramiko and all its diff --git a/paramiko/dsskey.py b/paramiko/dsskey.py index 2c90694f..8e0c2ba9 100644 --- a/paramiko/dsskey.py +++ b/paramiko/dsskey.py @@ -118,8 +118,8 @@ class DSSKey(PKey): m = Message() m.add_string('ssh-dss') # apparently, in rare cases, r or s may be shorter than 20 bytes! - rstr = util.deflate_long(int(r), 0) - sstr = util.deflate_long(int(s), 0) + rstr = util.deflate_long(r, 0) + sstr = util.deflate_long(s, 0) if len(rstr) < 20: rstr = zero_byte * (20 - len(rstr)) + rstr if len(sstr) < 20: diff --git a/paramiko/ecdsakey.py b/paramiko/ecdsakey.py index bc76b639..2f5c2c31 100644 --- a/paramiko/ecdsakey.py +++ b/paramiko/ecdsakey.py @@ -32,9 +32,6 @@ from cryptography.hazmat.primitives.asymmetric.utils import ( decode_rfc6979_signature, encode_rfc6979_signature ) -from pyasn1.codec.der import encoder -from pyasn1.type import namedtype, namedval, tag, univ - from paramiko.common import four_byte, one_byte, zero_byte from paramiko.message import Message from paramiko.pkey import PKey @@ -43,40 +40,6 @@ from paramiko.ssh_exception import SSHException from paramiko.util import deflate_long, inflate_long -# RFC 5480, section 2.1.1 -class _ECParameters(univ.Choice): - # TODO: There are a few more options for this choice I think, the RFC says - # not to use them though... - componentType = namedtype.NamedTypes( - namedtype.NamedType("namedCurve", univ.ObjectIdentifier()), - ) - - -# RFC 5915, Appendix A -class _ECPrivateKey(univ.Sequence): - componentType = namedtype.NamedTypes( - namedtype.NamedType( - "version", - univ.Integer( - namedValues=namedval.NamedValues( - ("ecPrivkeyVer1", 1), - ) - ), - ), - namedtype.NamedType("privateKey", univ.OctetString()), - namedtype.OptionalNamedType("parameters", _ECParameters().subtype( - implicitTag=tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 0), - )), - namedtype.OptionalNamedType("publicKey", univ.BitString().subtype( - implicitTag=tag.Tag(tag.tagClassContext, tag.tagFormatSimple, 1), - )), - ) - - -_CURVE_TO_OID = { - ec.SECP256R1: univ.ObjectIdentifier("1.2.840.10045.3.1.7") -} - class ECDSAKey(PKey): """ Representation of an ECDSA key which can be used to sign and verify SSH2 @@ -216,40 +179,17 @@ class ECDSAKey(PKey): byte_chr(5) * 5, byte_chr(6) * 6, byte_chr(7) * 7] def _decode_key(self, data): - s = """ ------BEGIN EC PRIVATE KEY----- -%s ------END EC PRIVATE KEY----- -""" % "\n".join(textwrap.wrap(base64.b64encode(data).decode(), 64)) - key = serialization.load_pem_private_key(s.encode(), password=None, backend=default_backend()) + key = serialization.load_der_private_key(data, password=None, backend=default_backend()) self.signing_key = key self.verifying_key = key.public_key() self.size = key.curve.key_size def _to_der(self, key): - private_numbers = key.private_numbers() - public_numbers = private_numbers.public_numbers - - private_key = deflate_long( - private_numbers.private_value, add_sign_padding=False + return key.private_bytes( + serialization.Encoding.DER, + serialization.Format.TraditionalOpenSSL, + serialization.NoEncryption(), ) - x_str = deflate_long(public_numbers.x, add_sign_padding=False) - y_str = deflate_long(public_numbers.y, add_sign_padding=False) - - key_length = key.curve.key_size // 8 - if len(x_str) < key_length: - x_str = zero_byte * (key_length - len(x_str)) + x_str - if len(y_str) < key_length: - y_str = zero_byte * (key_length - len(y_str)) + y_str - public_key = b"\x04" + x_str + y_str - - asn1_key = _ECPrivateKey() - asn1_key.setComponentByName("version", 1) - asn1_key.setComponentByName("privateKey", private_key) - asn1_key.setComponentByName("parameters") - asn1_key.getComponentByName("parameters").setComponentByName("namedCurve", _CURVE_TO_OID[type(key.curve)]) - asn1_key.setComponentByName("publicKey", "'%s'H" % binascii.hexlify(public_key).decode()) - return encoder.encode(asn1_key) def _sigencode(self, r, s): msg = Message() diff --git a/setup.py b/setup.py index e10a6390..a4977c15 100644 --- a/setup.py +++ b/setup.py @@ -41,7 +41,7 @@ try: from setuptools import setup kw = { 'install_requires': [ - 'cryptography >= 0.7', + 'cryptography >= 0.8', 'pyasn1 >= 0.1.7', ], } diff --git a/sites/www/installing.rst b/sites/www/installing.rst index dc20590e..57b639f0 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -20,10 +20,8 @@ We currently support **Python 2.6, 2.7, 3.3+, and PyPy** (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. -Paramiko has three hard dependencies: the pure-Python ECDSA module ``ecdsa`` -and ASN1 module ``pyasn1``, and the Cryptography library. ``ecdsa`` is easily -installable from wherever you obtained Paramiko's package; Cryptography may -require more work. Read on for details. +Paramiko has two hard dependencies: the pure-Python ASN1 module ``pyasn1``, and +the Cryptography library. Read on for details on installing ``cryptography``. If you need GSS-API / SSPI support, see :ref:`the below subsection on it ` for details on additional dependencies. diff --git a/tox-requirements.txt b/tox-requirements.txt index 23ed06d8..47ddd792 100644 --- a/tox-requirements.txt +++ b/tox-requirements.txt @@ -1,3 +1,3 @@ # Not sure why tox can't just read setup.py? -cryptography >= 0.7 +cryptography >= 0.8 pyasn1 >= 0.1.7 -- cgit v1.2.3 From 4c8e1574d3a736ad129d3925595966f6e93bbeca Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 1 Apr 2015 18:37:35 -0400 Subject: Fixed extra comma --- sites/www/installing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 57b639f0..9da7c23d 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -60,7 +60,7 @@ C extension ----------- Unless you are installing from a precompiled source such as a Debian apt -repository or RedHat RPM,, you will also need the ability to build Python +repository or RedHat RPM, you will also need the ability to build Python C-based modules from source in order to install Cryptography. 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 -- cgit v1.2.3 From 9e67e71377cea9adaaeab6dbb024f2af94ba7999 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Sat, 1 Aug 2015 08:46:43 -0400 Subject: removed references to python 3.2, which has basically no usage --- .travis.yml | 6 ++---- README | 2 +- sites/www/installing.rst | 5 ++--- tox.ini | 2 +- 4 files changed, 6 insertions(+), 9 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/.travis.yml b/.travis.yml index 9a55dbb6..5f444d93 100644 --- a/.travis.yml +++ b/.travis.yml @@ -3,7 +3,6 @@ sudo: false python: - "2.6" - "2.7" - - "3.2" - "3.3" - "3.4" install: @@ -19,9 +18,8 @@ script: # Run 'docs' first since its objects.inv is referred to by 'www'. # Also force warnings to be errors since most of them tend to be actual # problems. - # Finally, skip them under Python 3.2 due to sphinx shenanigans - - "[[ $TRAVIS_PYTHON_VERSION != 3.2 ]] && invoke docs -o -W || true" - - "[[ $TRAVIS_PYTHON_VERSION != 3.2 ]] && invoke www -o -W || true" + - "invoke docs -o -W || true" + - "invoke www -o -W || true" notifications: irc: channels: "irc.freenode.org#paramiko" diff --git a/README b/README index 36d7055f..4fea58cb 100644 --- a/README +++ b/README @@ -35,7 +35,7 @@ Requirements ------------ - Python 2.6 or better - this includes Python - 3.2 and higher as well. + 3.3 and higher as well. - Cryptography 0.8 or better - pyasn1 0.1.7 or better diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 9da7c23d..1865ddfc 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -16,9 +16,8 @@ via `pip `_:: Users who want the bleeding edge can install the development version via ``pip install paramiko==dev``. -We currently support **Python 2.6, 2.7, 3.3+, and PyPy** (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 are urged to upgrade. Paramiko has two hard dependencies: the pure-Python ASN1 module ``pyasn1``, and the Cryptography library. Read on for details on installing ``cryptography``. diff --git a/tox.ini b/tox.ini index 3d7c86da..d420c1a3 100644 --- a/tox.ini +++ b/tox.ini @@ -1,5 +1,5 @@ [tox] -envlist = py26,py27,py32,py33,py34,pypy +envlist = py26,py27,py33,py34,pypy [testenv] commands = pip install -q -r tox-requirements.txt -- cgit v1.2.3 From f5ba7d5a60110ea7236492f66406f542a09d88a3 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 4 Nov 2015 10:16:33 -0500 Subject: add this back in --- sites/www/installing.rst | 1 + 1 file changed, 1 insertion(+) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 1865ddfc..9f1f9080 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -72,6 +72,7 @@ For **Windows** users we recommend using the most recent version of ``pip``, Cryptography has binary wheels on PyPI, which remove the need for having a C compiler. +.. _gssapi: Optional dependencies for GSS-API / SSPI / Kerberos =================================================== -- cgit v1.2.3 From 37294eeb5c379fc32ae2cdf0563407b5a4a3c869 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sat, 23 Apr 2016 14:47:37 -0700 Subject: Tweaks to install docs re #394 --- sites/www/installing.rst | 57 +++++++++++++++++++++++++----------------------- 1 file changed, 30 insertions(+), 27 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 9f1f9080..bb1addc8 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -16,14 +16,15 @@ via `pip `_:: Users who want the bleeding edge can install the development version via ``pip install paramiko==dev``. -We currently support **Python 2.6, 2.7, 3.3+, and PyPy** 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 ASN1 module ``pyasn1``, and -the Cryptography library. Read on for details on installing ``cryptography``. +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 -` for details on additional dependencies. +` for details on its optional dependencies. + .. _release-lines: @@ -34,43 +35,45 @@ 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. +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. + If you're unsure which version to install, we have suggestions: * **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.) + probably get the **oldest actively supported line** (check the + :ref:`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. +.. _cryptography: + Cryptography ============ `Cryptography `_ provides the low-level (C-based) -encryption algorithms we need to implement the SSH protocol. There are a few -things to be aware of when installing Cryptography, because it includes a -C-extension. - -C extension ------------ - -Unless you are installing from a precompiled source such as a Debian apt -repository or RedHat RPM, you will also need the ability to build Python -C-based modules from source in order to install Cryptography. 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, OpenSSL headers, often named -``libssl-dev``, and libffi development libraries, often named ``libffi-dev``. - -For **Windows** users we recommend using the most recent version of ``pip``, -Cryptography has binary wheels on PyPI, which remove the need for having a C -compiler. +encryption algorithms we need to implement the SSH protocol. It has detailed +`installation instructions `_ (and an `FAQ +`_) which you should read carefully. + +In general, you'll need one of the following setups: + +* 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 CFFI. + Again, see `Cryptography's install docs `_; these + requirements may occasionally change. + +.. _crypto-install: https://cryptography.io/en/latest/installation/ + .. _gssapi: -- cgit v1.2.3 From 126c0fbca806e52a687eacf59a263eaba29820f6 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sat, 23 Apr 2016 16:16:30 -0700 Subject: Splice 1.x install docs back in as standalone document. Plus related tweaks --- sites/www/installing-1.x.rst | 94 ++++++++++++++++++++++++++++++++++++++++++++ sites/www/installing.rst | 41 ++++++++++++++----- 2 files changed, 125 insertions(+), 10 deletions(-) create mode 100644 sites/www/installing-1.x.rst (limited to 'sites/www/installing.rst') 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 `. +* Users on Windows may want to opt for the :ref:`pypm` approach. + + +.. _pycrypto: + +PyCrypto +======== + +`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 `, 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 `_ or obtaining a +precompiled Win32 PyCrypto package from `voidspace's Python modules page +`_. + +.. 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 + `_ for info. + + +.. _pypm: + +ActivePython and PyPM +===================== + +Windows users who already have ActiveState's `ActivePython +`_ distribution installed +may find Paramiko is best installed with `its package manager, 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 `_ ``0.1.7`` or better. diff --git a/sites/www/installing.rst b/sites/www/installing.rst index bb1addc8..51f317dc 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 @@ -37,16 +44,17 @@ for the last 2-3 releases including the latest stable one. 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. +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, we have suggestions: +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** (check the - :ref:`changelog` for recent releases). +* **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. @@ -57,9 +65,9 @@ If you're unsure which version to install, we have suggestions: Cryptography ============ -`Cryptography `_ provides the low-level (C-based) +`Cryptography `__ provides the low-level (C-based) encryption algorithms we need to implement the SSH protocol. It has detailed -`installation instructions `_ (and an `FAQ +`installation instructions`_ (and an `FAQ `_) which you should read carefully. In general, you'll need one of the following setups: @@ -69,10 +77,17 @@ In general, you'll need one of the following setups: 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 CFFI. - Again, see `Cryptography's install docs `_; these - requirements may occasionally change. + Again, see `Cryptography's install docs`_; these requirements may + occasionally change. -.. _crypto-install: https://cryptography.io/en/latest/installation/ + .. 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. + +.. _installation instructions: +.. _Cryptography's install docs: https://cryptography.io/en/latest/installation/ .. _gssapi: @@ -99,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 -- cgit v1.2.3 From 884e1f72e64b37be5f15cf9962e31bb1b028cbf8 Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Sat, 23 Apr 2016 16:59:40 -0700 Subject: s/CFFI/libffi/ as per @reaperhulk --- sites/www/installing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'sites/www/installing.rst') diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 51f317dc..5a41a76b 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -76,8 +76,8 @@ In general, you'll need one of the following setups: 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 CFFI. - Again, see `Cryptography's install docs`_; these requirements may + C build toolchain, plus development headers for Python, OpenSSL and + ``libffi``. Again, see `Cryptography's install docs`_; these requirements may occasionally change. .. warning:: -- cgit v1.2.3