From 3c7813683b1845959aca706eaa23f062a006356b Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 19:47:36 +0200 Subject: Adding upstream version 3.4.0. Signed-off-by: Daniel Baumann --- sites/docs/.readthedocs.yaml | 13 + sites/docs/api/agent.rst | 6 + sites/docs/api/auth.rst | 8 + sites/docs/api/buffered_pipe.rst | 4 + sites/docs/api/channel.rst | 4 + sites/docs/api/client.rst | 5 + sites/docs/api/config.rst | 135 +++ sites/docs/api/file.rst | 4 + sites/docs/api/hostkeys.rst | 5 + sites/docs/api/kex_gss.rst | 5 + sites/docs/api/keys.rst | 28 + sites/docs/api/message.rst | 4 + sites/docs/api/packet.rst | 4 + sites/docs/api/pipe.rst | 4 + sites/docs/api/proxy.rst | 4 + sites/docs/api/server.rst | 5 + sites/docs/api/sftp.rst | 13 + sites/docs/api/ssh_exception.rst | 4 + sites/docs/api/ssh_gss.rst | 17 + sites/docs/api/transport.rst | 5 + sites/docs/conf.py | 28 + sites/docs/index.rst | 75 ++ sites/shared_conf.py | 33 + sites/www/.readthedocs.yaml | 13 + sites/www/_templates/rss.xml | 19 + sites/www/changelog.rst | 1668 ++++++++++++++++++++++++++++++++++++++ sites/www/conf.py | 28 + sites/www/contact.rst | 12 + sites/www/contributing.rst | 25 + sites/www/faq.rst | 36 + sites/www/index.rst | 13 + sites/www/installing-1.x.rst | 121 +++ sites/www/installing.rst | 152 ++++ 33 files changed, 2500 insertions(+) create mode 100644 sites/docs/.readthedocs.yaml create mode 100644 sites/docs/api/agent.rst create mode 100644 sites/docs/api/auth.rst create mode 100644 sites/docs/api/buffered_pipe.rst create mode 100644 sites/docs/api/channel.rst create mode 100644 sites/docs/api/client.rst create mode 100644 sites/docs/api/config.rst create mode 100644 sites/docs/api/file.rst create mode 100644 sites/docs/api/hostkeys.rst create mode 100644 sites/docs/api/kex_gss.rst create mode 100644 sites/docs/api/keys.rst create mode 100644 sites/docs/api/message.rst create mode 100644 sites/docs/api/packet.rst create mode 100644 sites/docs/api/pipe.rst create mode 100644 sites/docs/api/proxy.rst create mode 100644 sites/docs/api/server.rst create mode 100644 sites/docs/api/sftp.rst create mode 100644 sites/docs/api/ssh_exception.rst create mode 100644 sites/docs/api/ssh_gss.rst create mode 100644 sites/docs/api/transport.rst create mode 100644 sites/docs/conf.py create mode 100644 sites/docs/index.rst create mode 100644 sites/shared_conf.py create mode 100644 sites/www/.readthedocs.yaml create mode 100644 sites/www/_templates/rss.xml create mode 100644 sites/www/changelog.rst create mode 100644 sites/www/conf.py create mode 100644 sites/www/contact.rst create mode 100644 sites/www/contributing.rst create mode 100644 sites/www/faq.rst create mode 100644 sites/www/index.rst create mode 100644 sites/www/installing-1.x.rst create mode 100644 sites/www/installing.rst (limited to 'sites') diff --git a/sites/docs/.readthedocs.yaml b/sites/docs/.readthedocs.yaml new file mode 100644 index 0000000..3212c93 --- /dev/null +++ b/sites/docs/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: "ubuntu-22.04" + tools: + python: "3.7" + +python: + install: + - requirements: dev-requirements.txt + +sphinx: + configuration: sites/docs/conf.py diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst new file mode 100644 index 0000000..f01ad97 --- /dev/null +++ b/sites/docs/api/agent.rst @@ -0,0 +1,6 @@ +SSH agents +========== + +.. automodule:: paramiko.agent + :inherited-members: + :no-special-members: diff --git a/sites/docs/api/auth.rst b/sites/docs/api/auth.rst new file mode 100644 index 0000000..b6bce36 --- /dev/null +++ b/sites/docs/api/auth.rst @@ -0,0 +1,8 @@ +Authentication modules +====================== + +.. automodule:: paramiko.auth_strategy + :member-order: bysource + +.. automodule:: paramiko.auth_handler + :member-order: bysource diff --git a/sites/docs/api/buffered_pipe.rst b/sites/docs/api/buffered_pipe.rst new file mode 100644 index 0000000..54d87c5 --- /dev/null +++ b/sites/docs/api/buffered_pipe.rst @@ -0,0 +1,4 @@ +Buffered pipes +============== + +.. automodule:: paramiko.buffered_pipe diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst new file mode 100644 index 0000000..e71526f --- /dev/null +++ b/sites/docs/api/channel.rst @@ -0,0 +1,4 @@ +Channel +======= + +.. automodule:: paramiko.channel diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst new file mode 100644 index 0000000..b201812 --- /dev/null +++ b/sites/docs/api/client.rst @@ -0,0 +1,5 @@ +Client +====== + +.. automodule:: paramiko.client + :member-order: bysource diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst new file mode 100644 index 0000000..9015a77 --- /dev/null +++ b/sites/docs/api/config.rst @@ -0,0 +1,135 @@ +============= +Configuration +============= + +Paramiko **does not itself** leverage `OpenSSH-style config file directives +`_, but it **does** implement a parser for the format, which users +can honor themselves (and is used by higher-level libraries, such as +`Fabric`_). + +The API for this is `.SSHConfig`, which loads SSH config files from disk, +file-like object, or string and exposes a "look up a hostname, get a dict of +applicable keywords/values back" functionality. + +As with OpenSSH's own support, this dict will contain values from across the +parsed file, depending on the order in which keywords were encountered and how +specific or generic the ``Host`` or ``Match`` directives were. + +.. note:; + Result keys are lowercased for consistency and ease of deduping, as the + overall parsing/matching is itself case-insensitive. Thus, a source file + containing e.g. ``ProxyCommand`` will result in lookup results like + ``{"proxycommand": "shell command here"}``. + + +.. _ssh-config-support: + +Keywords currently supported +============================ + +The following is an alphabetical list of which `ssh_config`_ directives +Paramiko interprets during the parse/lookup process (as above, actual SSH +connections **do not** reference parsed configs). Departures from `OpenSSH's +implementation `_ (e.g. to support backwards compat with older +Paramiko releases) are included. A keyword by itself means no known departures. + +- ``AddressFamily``: used when looking up the local hostname for purposes of + expanding the ``%l``/``%L`` :ref:`tokens ` (this is actually a minor + value-add on top of OpenSSH, which doesn't actually honor this setting when + expanding ``%l``). +- ``CanonicalDomains`` + + .. versionadded:: 2.7 + +- ``CanonicalizeFallbackLocal``: when ``no``, triggers raising of + `.CouldNotCanonicalize` for target hostnames which do not successfully + canonicalize. + + .. versionadded:: 2.7 + +- ``CanonicalizeHostname``: along with the other ``Canonicaliz*`` settings + (sans ``CanonicalizePermittedCNAMEs``, which is not yet implemented), enables + hostname canonicalization, insofar as calling `.SSHConfig.lookup` with a + given hostname will return a canonicalized copy of the config data, including + an updated ``HostName`` value. + + .. versionadded:: 2.7 + +- ``CanonicalizeMaxDots`` + + .. versionadded:: 2.7 + +- ``Host`` +- ``HostName``: used in ``%h`` :ref:`token expansion ` +- ``Match``: supports the keywords ``all``, ``canonical``, ``exec``, ``final``, + ``host``, ``localuser``, ``originalhost``, and ``user``, with the following + caveats: + + - You must have the optional dependency Invoke installed; see :ref:`the + installation docs ` (in brief: install + ``paramiko[invoke]`` or ``paramiko[all]``). + - As usual, connection-time information is not present during config + lookup, and thus cannot be used to determine matching. This primarily + impacts ``Match user``, which can match against loaded ``User`` values + but has no knowledge about connection-time usernames. + + .. versionadded:: 2.7 + .. versionchanged:: 3.3 + Added support for the ``final`` keyword. + +- ``Port``: supplies potential values for ``%p`` :ref:`token expansion + `. +- ``ProxyCommand``: see our `.ProxyCommand` class for an easy + way to honor this keyword from a config you've parsed. + + - Honors :ref:`token expansion `. + - When a lookup would result in an effective ``ProxyCommand none``, + Paramiko (as of 1.x-2.x) strips it from the resulting dict entirely. A + later major version may retain the ``"none"`` marker for clarity's sake. + +- ``User``: supplies potential values for ``%u`` :ref:`token expansion + `. + +.. _TOKENS: + +Expansion tokens +---------------- + +We support most SSH config expansion tokens where possible, so when they are +present in a config file source, the result of a `.SSHConfig.lookup` will +contain the expansions/substitutions (based on the rest of the config or +properties of the local system). + +Specifically, we are known to support the below, where applicable (e.g. as in +OpenSSH, ``%L`` works in ``ControlPath`` but not elsewhere): + +- ``%C`` +- ``%d`` +- ``%h`` +- ``%l`` +- ``%L`` +- ``%n`` +- ``%p`` +- ``%r`` +- ``%u``: substitutes the configured ``User`` value, or the local user (as seen + by ``getpass.getuser``) if not specified. + +In addition, we extend OpenSSH's tokens as follows: + +- ``~`` is treated like ``%d`` (expands to the local user's home directory + path) when expanding ``ProxyCommand`` values, since ``ProxyCommand`` does not + natively support ``%d`` for some reason. + + +.. _ssh_config: https://man.openbsd.org/ssh_config +.. _Fabric: http://fabfile.org + + +``config`` module API documentation +=================================== + +Mostly of interest to contributors; see previous section for behavioral +details. + +.. automodule:: paramiko.config + :member-order: bysource diff --git a/sites/docs/api/file.rst b/sites/docs/api/file.rst new file mode 100644 index 0000000..199f3ec --- /dev/null +++ b/sites/docs/api/file.rst @@ -0,0 +1,4 @@ +Buffered files +============== + +.. automodule:: paramiko.file diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst new file mode 100644 index 0000000..770652f --- /dev/null +++ b/sites/docs/api/hostkeys.rst @@ -0,0 +1,5 @@ +Host keys / ``known_hosts`` files +================================= + +.. automodule:: paramiko.hostkeys + :member-order: bysource diff --git a/sites/docs/api/kex_gss.rst b/sites/docs/api/kex_gss.rst new file mode 100644 index 0000000..9fd0922 --- /dev/null +++ b/sites/docs/api/kex_gss.rst @@ -0,0 +1,5 @@ +GSS-API key exchange +==================== + +.. automodule:: paramiko.kex_gss + :member-order: bysource diff --git a/sites/docs/api/keys.rst b/sites/docs/api/keys.rst new file mode 100644 index 0000000..a456f50 --- /dev/null +++ b/sites/docs/api/keys.rst @@ -0,0 +1,28 @@ +============ +Key handling +============ + +Parent key class +================ + +.. automodule:: paramiko.pkey + +DSA (DSS) +========= + +.. automodule:: paramiko.dsskey + +RSA +=== + +.. automodule:: paramiko.rsakey + +ECDSA +===== + +.. automodule:: paramiko.ecdsakey + +Ed25519 +======= + +.. automodule:: paramiko.ed25519key diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst new file mode 100644 index 0000000..8d531e0 --- /dev/null +++ b/sites/docs/api/message.rst @@ -0,0 +1,4 @@ +Message +======= + +.. automodule:: paramiko.message diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst new file mode 100644 index 0000000..4089203 --- /dev/null +++ b/sites/docs/api/packet.rst @@ -0,0 +1,4 @@ +Packetizer +========== + +.. automodule:: paramiko.packet diff --git a/sites/docs/api/pipe.rst b/sites/docs/api/pipe.rst new file mode 100644 index 0000000..e480446 --- /dev/null +++ b/sites/docs/api/pipe.rst @@ -0,0 +1,4 @@ +Cross-platform pipe implementations +=================================== + +.. automodule:: paramiko.pipe diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst new file mode 100644 index 0000000..489b14e --- /dev/null +++ b/sites/docs/api/proxy.rst @@ -0,0 +1,4 @@ +``ProxyCommand`` support +======================== + +.. automodule:: paramiko.proxy diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst new file mode 100644 index 0000000..ea85454 --- /dev/null +++ b/sites/docs/api/server.rst @@ -0,0 +1,5 @@ +Server implementation +===================== + +.. automodule:: paramiko.server + :member-order: bysource diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst new file mode 100644 index 0000000..956eada --- /dev/null +++ b/sites/docs/api/sftp.rst @@ -0,0 +1,13 @@ +SFTP +==== + +.. automodule:: paramiko.sftp +.. automodule:: paramiko.sftp_client +.. automodule:: paramiko.sftp_server +.. automodule:: paramiko.sftp_attr +.. automodule:: paramiko.sftp_file + :inherited-members: + :no-special-members: + :show-inheritance: +.. automodule:: paramiko.sftp_handle +.. automodule:: paramiko.sftp_si diff --git a/sites/docs/api/ssh_exception.rst b/sites/docs/api/ssh_exception.rst new file mode 100644 index 0000000..64872dc --- /dev/null +++ b/sites/docs/api/ssh_exception.rst @@ -0,0 +1,4 @@ +Exceptions +========== + +.. automodule:: paramiko.ssh_exception diff --git a/sites/docs/api/ssh_gss.rst b/sites/docs/api/ssh_gss.rst new file mode 100644 index 0000000..155fcff --- /dev/null +++ b/sites/docs/api/ssh_gss.rst @@ -0,0 +1,17 @@ +GSS-API authentication +====================== + +.. automodule:: paramiko.ssh_gss + :member-order: bysource + +.. autoclass:: _SSH_GSSAuth + :member-order: bysource + +.. autoclass:: _SSH_GSSAPI_OLD + :member-order: bysource + +.. autoclass:: _SSH_GSSAPI_NEW + :member-order: bysource + +.. autoclass:: _SSH_SSPI + :member-order: bysource diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst new file mode 100644 index 0000000..7c9d9fd --- /dev/null +++ b/sites/docs/api/transport.rst @@ -0,0 +1,5 @@ +Transport +========= + +.. automodule:: paramiko.transport + :member-order: bysource diff --git a/sites/docs/conf.py b/sites/docs/conf.py new file mode 100644 index 0000000..79958e6 --- /dev/null +++ b/sites/docs/conf.py @@ -0,0 +1,28 @@ +# Obtain shared config values +import os, sys +from os.path import abspath, join, dirname + +sys.path.append(abspath("..")) +sys.path.append(abspath("../..")) +from shared_conf import * + +# Enable autodoc, intersphinx +extensions.extend(["sphinx.ext.autodoc"]) + +# Autodoc settings +autodoc_default_options = { + "members": True, + "special-members": True, +} + +# Default is 'local' building, but reference the public www site when building +# under RTD. +target = join(dirname(__file__), "..", "www", "_build") +if os.environ.get("READTHEDOCS") == "True": + target = "http://paramiko.org" +intersphinx_mapping["www"] = (target, None) + +# Sister-site links to WWW +html_theme_options["extra_nav_links"] = { + "Main website": "http://www.paramiko.org" +} diff --git a/sites/docs/index.rst b/sites/docs/index.rst new file mode 100644 index 0000000..675fe59 --- /dev/null +++ b/sites/docs/index.rst @@ -0,0 +1,75 @@ +==================================== +Welcome to Paramiko's documentation! +==================================== + +This site covers Paramiko's usage & API documentation. For basic info on what +Paramiko is, including its public changelog & how the project is maintained, +please see `the main project website `_. + + +API documentation +================= + +The high-level client API starts with creation of an `.SSHClient` object. For +more direct control, pass a socket (or socket-like object) to a `.Transport`, +and use `start_server <.Transport.start_server>` or `start_client +<.Transport.start_client>` to negotiate with the remote host as either a server +or client. + +As a client, you are responsible for authenticating using a password or private +key, and checking the server's host key. (Key signature and verification is +done by paramiko, but you will need to provide private keys and check that the +content of a public key matches what you expected to see.) + +As a server, you are responsible for deciding which users, passwords, and keys +to allow, and what kind of channels to allow. + +Once you have finished, either side may request flow-controlled `channels +<.Channel>` to the other side, which are Python objects that act like sockets, +but send and receive data over the encrypted session. + +For details, please see the following tables of contents (which are organized +by area of interest.) + + +Core SSH protocol classes +------------------------- + +.. toctree:: + api/channel + api/client + api/message + api/packet + api/transport + + +Authentication & keys +--------------------- + +.. toctree:: + api/auth + api/agent + api/hostkeys + api/keys + api/ssh_gss + api/kex_gss + + +Other primary functions +----------------------- + +.. toctree:: + api/config + api/proxy + api/server + api/sftp + + +Miscellany +---------- + +.. toctree:: + api/buffered_pipe + api/file + api/pipe + api/ssh_exception diff --git a/sites/shared_conf.py b/sites/shared_conf.py new file mode 100644 index 0000000..5e85def --- /dev/null +++ b/sites/shared_conf.py @@ -0,0 +1,33 @@ +from datetime import datetime + +import alabaster + + +# Alabaster theme + mini-extension +html_theme_path = [alabaster.get_path()] +extensions = ["alabaster", "sphinx.ext.intersphinx"] +# Paths relative to invoking conf.py - not this shared file +html_theme = "alabaster" +html_theme_options = { + "description": "A Python implementation of SSHv2.", + "github_user": "paramiko", + "github_repo": "paramiko", + "analytics_id": "UA-18486793-2", + "travis_button": False, + "tidelift_url": "https://tidelift.com/subscription/pkg/pypi-paramiko?utm_source=pypi-paramiko&utm_medium=referral&utm_campaign=docs", +} +html_sidebars = { + "**": ["about.html", "navigation.html", "searchbox.html", "donate.html"] +} + +# Everything intersphinx's to Python +intersphinx_mapping = {"python": ("https://docs.python.org/3.6/", None)} + +# Regular settings +project = "Paramiko" +copyright = f"{datetime.now().year} Jeff Forcier" +master_doc = "index" +templates_path = ["_templates"] +exclude_trees = ["_build"] +source_suffix = ".rst" +default_role = "obj" diff --git a/sites/www/.readthedocs.yaml b/sites/www/.readthedocs.yaml new file mode 100644 index 0000000..4f7d397 --- /dev/null +++ b/sites/www/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: "ubuntu-22.04" + tools: + python: "3.7" + +python: + install: + - requirements: dev-requirements.txt + +sphinx: + configuration: sites/www/conf.py diff --git a/sites/www/_templates/rss.xml b/sites/www/_templates/rss.xml new file mode 100644 index 0000000..f6f9cbd --- /dev/null +++ b/sites/www/_templates/rss.xml @@ -0,0 +1,19 @@ + + + + + {{ title }} + {{ link }} + {{ description }} + {{ date }} + {% for link, title, desc, date in posts %} + + {{ link }} + {{ link }} + <![CDATA[{{ title }}]]> + + {{ date }} + + {% endfor %} + + diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst new file mode 100644 index 0000000..b7d93b3 --- /dev/null +++ b/sites/www/changelog.rst @@ -0,0 +1,1668 @@ +========= +Changelog +========= + +- :release:`3.4.0 <2023-12-18>` +- :feature:`-` `Transport` grew a new ``packetizer_class`` kwarg for overriding + the packet-handler class used internally. Mostly for testing, but advanced + users may find this useful when doing deep hacks. +- :bug:`-` Address `CVE 2023-48795`_ (aka the + "Terrapin Attack", a vulnerability found in the SSH protocol re: treatment of + packet sequence numbers) as follows: + + - The vulnerability only impacts encrypt-then-MAC digest algorithms in + tandem with CBC ciphers, and ChaCha20-poly1305; of these, Paramiko + currently only implements ``hmac-sha2-(256|512)-etm`` in tandem with + ``AES-CBC``. If you are unable to upgrade to Paramiko versions containing + the below fixes right away, you may instead use the + ``disabled_algorithms`` connection option to disable the ETM MACs and/or + the CBC ciphers (this option is present in Paramiko >=2.6). + - As the fix for the vulnerability requires both ends of the connection to + cooperate, the below changes will only take effect when the remote end is + OpenSSH >= 9.6 (or equivalent, such as Paramiko in server mode, as of + this patch version) and configured to use the new "strict kex" mode. + Paramiko will always attempt to use "strict kex" mode if offered by the + server, unless you override this by specifying ``strict_kex=False`` in + `Transport.__init__`. + - Paramiko will now raise an `SSHException` subclass (`MessageOrderError`) + when protocol messages are received in unexpected order. This includes + situations like receiving ``MSG_DEBUG`` or ``MSG_IGNORE`` during initial + key exchange, which are no longer allowed during strict mode. + - Key (re)negotiation -- i.e. ``MSG_NEWKEYS``, whenever it is encountered + -- now resets packet sequence numbers. (This should be invisible to users + during normal operation, only causing exceptions if the exploit is + encountered, which will usually result in, again, `MessageOrderError`.) + - Sequence number rollover will now raise `SSHException` if it occurs + during initial key exchange (regardless of strict mode status). + + Thanks to Fabian Bäumer, Marcus Brinkmann, and Jörg Schwenk for submitting + details on the CVE prior to release. + +- :bug:`-` Tweak ``ext-info-(c|s)`` detection during KEXINIT protocol phase; + the original implementation made assumptions based on an OpenSSH + implementation detail. +- :release:`3.3.1 <2023-07-28>` +- :bug:`-` Cleaned up some very old root level files, mostly just to exercise + some of our doc build and release machinery. This changelog entry + intentionally left blank! ``nothing-to-see-here-move-along.gif`` +- :release:`3.3.0 <2023-07-28>` +- :feature:`1907` (solves :issue:`1992`) Add support and tests for ``Match + final …`` (frequently used in ProxyJump configurations to exclude the jump + host) to our :ref:`SSH config parser `. Patch by + ``@commonism``. +- :feature:`2058` (solves :issue:`1587` and possibly others) Add an explicit + ``max_concurrent_prefetch_requests`` argument to + `paramiko.client.SSHClient.get` and `paramiko.client.SSHClient.getfo`, + allowing users to limit the number of concurrent requests used during + prefetch. Patch by ``@kschoelhorn``, with a test by ``@bwinston-sdp``. +- :release:`3.2.0 <2023-05-25>` +- :bug:`- major` Fixed a very sneaky bug found at the apparently + rarely-traveled intersection of ``RSA-SHA2`` keys, certificates, SSH agents, + and stricter-than-OpenSSH server targets. This manifested as yet another + "well, if we turn off SHA2 at one end or another, everything works again" + problem, for example with version 12 of the Teleport server endpoint. + + This has been fixed; Paramiko tweaked multiple aspects of how it requests + agent signatures, and the agent appears to do the right thing now. + + Thanks to Ryan Stoner for the bug report and testing. +- :bug:`2012 major` (also :issue:`1961` and countless others) The + ``server-sig-algs`` and ``RSA-SHA2`` features added around Paramiko 2.9 or + so, had the annoying side effect of not working with servers that don't + support *either* of those feature sets, requiring use of + ``disabled_algorithms`` to forcibly disable the SHA2 algorithms on Paramiko's + end. + + The **experimental** `~paramiko.transport.ServiceRequestingTransport` (noted + in its own entry in this changelog) includes a fix for this issue, + specifically by falling back to the same algorithm as the in-use pubkey if + it's in the algorithm list (leaving the "first algorithm in said list" as an + absolute final fallback). +- :feature:`-` Implement ``_fields()`` on `~paramiko.agent.AgentKey` so that it + may be compared (via ``==``) with other `~paramiko.pkey.PKey` instances. +- :bug:`23 major` Since its inception, Paramiko has (for reasons lost to time) + implemented authentication as a side effect of handling affirmative replies + to ``MSG_SERVICE_REQUEST`` protocol messages. What this means is Paramiko + makes one such request before every ``MSG_USERAUTH_REQUEST``, i.e. every auth + attempt. + + OpenSSH doesn't care if clients send multiple service requests, but other + server implementations are often stricter in what they accept after an + initial service request (due to the RFCs not being clear). This can result in + odd behavior when a user doesn't authenticate successfully on the very first + try (for example, when the right key for a target host is the third in one's + ssh-agent). + + This version of Paramiko now contains an opt-in + `~paramiko.transport.Transport` subclass, + `~paramiko.transport.ServiceRequestingTransport`, which more-correctly + implements service request handling in the Transport, and uses an + auth-handler subclass internally which has been similarly adapted. Users + wanting to try this new experimental code path may hand this class to + `SSHClient.connect ` as its + ``transport_factory`` kwarg. + + .. warning:: + This feature is **EXPERIMENTAL** and its code may be subject to change. + + In addition: + - minor backwards incompatible changes exist in the new code paths, + most notably the removal of the (inconsistently applied and rarely + used) ``event`` arguments to the ``auth_xxx`` methods. + - GSSAPI support has only been partially implemented, and is untested. + + .. note:: + Some minor backwards-*compatible* changes were made to the **existing** + Transport and AuthHandler classes to facilitate the new code. For + example, ``Transport._handler_table`` and + ``AuthHandler._client_handler_table`` are now properties instead of raw + attributes. + +- :feature:`387` Users of `~paramiko.client.SSHClient` can now configure the + authentication logic Paramiko uses when connecting to servers; this + functionality is intended for advanced users and higher-level libraries such + as `Fabric `_. See `~paramiko.auth_strategy` for + details. + + Fabric's co-temporal release includes a proof-of-concept use of this feature, + implementing an auth flow much closer to that of the OpenSSH client (versus + Paramiko's legacy behavior). It is **strongly recommended** that if this + interests you, investigate replacing any direct use of ``SSHClient`` with + Fabric's ``Connection``. + + .. warning:: + This feature is **EXPERIMENTAL**; please see its docs for details. + +- :feature:`-` Enhanced `~paramiko.agent.AgentKey` with new attributes, such + as: + + - Added a ``comment`` attribute (and constructor argument); + `Agent.get_keys() ` now uses this kwarg to + store any comment field sent over by the agent. The original version of + the agent feature inexplicably did not store the comment anywhere. + - Agent-derived keys now attempt to instantiate a copy of the appropriate + key class for access to other algorithm-specific members (eg key size). + This is available as the ``.inner_key`` attribute. + + .. note:: + This functionality is now in use in Fabric's new ``--list-agent-keys`` + feature, as well as in Paramiko's debug logging. + +- :feature:`-` `~paramiko.pkey.PKey` now offers convenience + "meta-constructors", static methods that simplify the process of + instantiating the correct subclass for a given key input. + + For example, `PKey.from_path ` can load a file + path without knowing *a priori* what type of key it is (thanks to some handy + methods within our cryptography dependency). Going forwards, we expect this + to be the primary method of loading keys by user code that runs on "human + time" (i.e. where some minor efficiencies are worth the convenience). + + In addition, `PKey.from_type_string ` + now exists, and is being used in some internals to load ssh-agent keys. + + As part of these changes, `~paramiko.pkey.PKey` and friends grew an + `~paramiko.pkey.PKey.identifiers` classmethod; this is inspired by the + `~paramiko.ecdsakey.ECDSAKey.supported_key_format_identifiers` classmethod + (which now refers to the new method.) This also includes adding a ``.name`` + attribute to most key classes (which will eventually replace ``.get_name()``. + +- :feature:`-` `~paramiko.pkey.PKey` grew a new ``.algorithm_name`` property + which displays the key algorithm; this is typically derived from the value of + `~paramiko.pkey.PKey.get_name`. For example, ED25519 keys have a ``get_name`` + of ``ssh-ed25519`` (the SSH protocol key type field value), and now have a + ``algorithm_name`` of ``ED25519``. +- :feature:`-` `~paramiko.pkey.PKey` grew a new ``.fingerprint`` property which + emits a fingerprint string matching the SHA256+Base64 values printed by + various OpenSSH tooling (eg ``ssh-add -l``, ``ssh -v``). This is intended to + help troubleshoot Paramiko-vs-OpenSSH behavior and will eventually replace + the venerable ``get_fingerprint`` method. +- :bug:`- major` `~paramiko.agent.AgentKey` had a dangling Python 3 + incompatible ``__str__`` method returning bytes. This method has been + removed, allowing the superclass' (`~paramiko.pkey.PKey`) method to run + instead. +- :release:`3.1.0 <2023-03-10>` +- :feature:`2013` (solving :issue:`2009`, plus others) Add an explicit + ``channel_timeout`` keyword argument to `paramiko.client.SSHClient.connect`, + allowing users to configure the previously-hardcoded default value of 3600 + seconds. Thanks to ``@VakarisZ`` and ``@ilija-lazoroski`` for the report and + patch, with credit to Mike Salvatore for patch review. +- :feature:`2173` Accept single tabs as field separators (in addition to + single spaces) in `` for parity + with OpenSSH's KnownHosts parser. Patched by Alex Chavkin. +- :support:`2178 backported` Apply ``codespell`` to the codebase, which found a + lot of very old minor spelling mistakes in docstrings. Also modernize many + instances of ``*largs`` vs ``*args`` and ``**kwarg`` vs ``**kwargs``. Patch + courtesy of Yaroslav Halchenko, with review from Brian Skinn. +- :release:`3.0.0 <2023-01-20>` +- :bug:`2110 major` Remove some unnecessary ``__repr__`` calls when handling + bytes-vs-str conversions. This was apparently doing a lot of unintentional + data processing, which adds up in some use cases -- such as SFTP transfers, + which may now be significantly faster. Kudos to Shuhua Zhong for catch & + patch. +- :bug:`2165 major` Streamline some redundant (and costly) byte conversion + calls in the packetizer and the core SFTP module. This should lead to some + SFTP speedups at the very least. Thanks to Alex Gaynor for the patch. +- :support:`-` ``paramiko.util.retry_on_signal`` (and any internal uses of + same, and also any internal retries of ``EINTR`` on eg socket operations) has + been removed. As of Python 3.5, per `PEP 475 + `_, this functionality (and retrying + ``EINTR`` generally) is now part of the standard library. + + .. warning:: + This change is backwards incompatible if you were explicitly + importing/using this particular function. The observable behavior otherwise + should not be changing. + +- :support:`732` (also re: :issue:`630`) `~paramiko.config.SSHConfig` used to + straight-up delete the ``proxycommand`` key from config lookup results when + the source config said ``ProxyCommand none``. This has been altered to + preserve the key and give it the Python value ``None``, thus making the + Python representation more in line with the source config file. + + .. warning:: + This change is backwards incompatible if you were relying on the old (1.x, + 2.x) behavior for some reason (eg assuming all ``proxycommand`` values were + valid subcommand strings). + +- :support:`-` The behavior of private key classes' (ie anything inheriting + from `~paramiko.pkey.PKey`) private key writing methods used to perform a + manual, extra ``chmod`` call after writing. This hasn't been strictly + necessary since the mid 2.x release line (when key writing started giving the + ``mode`` argument to `os.open`), and has now been removed entirely. + + This should only be observable if you were mocking Paramiko's system calls + during your own testing, or similar. +- :support:`-` ``PKey.__cmp__`` has been removed. Ordering-oriented comparison + of key files is unlikely to have ever made sense (the old implementation + attempted to order by the hashes of the key material) and so we have not + bothered setting up ``__lt__`` and friends at this time. The class continues + to have its original ``__eq__`` untouched. + + .. warning:: + This change is backwards incompatible if you were actually trying to sort + public key objects (directly or indirectly). Please file bug reports + detailing your use case if you have some intractable need for this + behavior, and we'll consider adding back the necessary Python 3 magic + methods so that it works as before. + +- :bug:`- major` A handful of lower-level classes (notably + `paramiko.message.Message` and `paramiko.pkey.PKey`) previously returned + `bytes` objects from their implementation of ``__str__``, even under Python + 3; and there was never any ``__bytes__`` method. + + These issues have been fixed by renaming ``__str__`` to ``__bytes__`` and + relying on Python's default "stringification returns the output of + ``__repr__``" behavior re: any real attempts to ``str()`` such objects. +- :support:`-` ``paramiko.common.asbytes`` has been moved to + ``paramiko.util.asbytes``. + + .. warning:: + This change is backwards incompatible if you were directly using this + function (which is unlikely). + +- :support:`-` Remove the now irrelevant ``paramiko.py3compat`` module. + + .. warning:: + This change is backwards incompatible. Such references should be + search-and-replaced with their modern Python 3.6+ equivalents; in some + cases, still-useful methods or values have been moved to ``paramiko.util`` + (most) or ``paramiko.common`` (``byte_*``). + +- :support:`-` Drop support for Python versions less than 3.6, including Python + 2. So long and thanks for all the fish! + + .. warning:: + This change is backwards incompatible. However, our packaging metadata has + been updated to include ``python_requires``, so this should not cause + breakage unless you're on an old installation method that can't read this + metadata. + + .. note:: + As part of this change, our dependencies have been updated; eg we now + require Cryptography>=3.3, up from 2.5. + +- :release:`2.12.0 <2022-11-04>` +- :feature:`2125` (also re: :issue:`2054`) Add a ``transport_factory`` kwarg to + `SSHClient.connect ` for advanced + users to gain more control over early Transport setup and manipulation. + Thanks to Noah Pederson for the patch. +- :release:`2.11.1 <2022-11-04>` +- :release:`2.10.6 <2022-11-04>` +- :bug:`1822` (via, and relating to, far too many other issues to mention here) + Update `~paramiko.client.SSHClient` so it explicitly closes its wrapped + socket object upon encountering socket errors at connection time. This should + help somewhat with certain classes of memory leaks, resource warnings, and/or + errors (though we hasten to remind everyone that Client and Transport have + their own ``.close()`` methods for use in non-error situations!). Patch + courtesy of ``@YoavCohen``. +- bug:`1637` (via :issue:`1599`) Raise `~paramiko.ssh_exception.SSHException` + explicitly when blank private key data is loaded, instead of the natural + result of ``IndexError``. This should help more bits of Paramiko or + Paramiko-adjacent codebases to correctly handle this class of error. Credit: + Nicholas Dietz. +- :release:`2.11.0 <2022-05-16>` +- :release:`2.10.5 <2022-05-16>` +- :release:`2.9.5 <2022-05-16>` +- :bug:`1933` Align signature verification algorithm with OpenSSH re: + zero-padding signatures which don't match their nominal size/length. This + shouldn't affect most users, but will help Paramiko-implemented SSH servers + handle poorly behaved clients such as PuTTY. Thanks to Jun Omae for catch & + patch. +- :bug:`2017` OpenSSH 7.7 and older has a bug preventing it from understanding + how to perform SHA2 signature verification for RSA certificates (specifically + certs - not keys), so when we added SHA2 support it broke all clients using + RSA certificates with these servers. This has been fixed in a manner similar + to what OpenSSH's own client does: a version check is performed and the + algorithm used is downgraded if needed. Reported by Adarsh Chauhan, with fix + suggested by Jun Omae. +- :support:`2038` (via :issue:`2039`) Recent versions of Cryptography have + deprecated Blowfish algorithm support; in lieu of an easy method for users to + remove it from the list of algorithms Paramiko tries to import and use, we've + decided to remove it from our "preferred algorithms" list. This will both + discourage use of a weak algorithm, and avoid warnings. Credit for + report/patch goes to Mike Roest. +- :bug:`2008` (via :issue:`2010`) Windows-native SSH agent support as merged in + 2.10 could encounter ``Errno 22`` ``OSError`` exceptions in some scenarios + (eg server not cleanly closing a relevant named pipe). This has been worked + around and should be less problematic. Reported by Danilo Campana Fuchs and + patched by Jun Omae. +- :release:`2.10.4 <2022-04-25>` +- :release:`2.9.4 <2022-04-25>` +- :support:`1838 backported` (via :issue:`1870`/:issue:`2028`) Update + ``camelCase`` method calls against the ``threading`` module to be + ``snake_case``; this and related tweaks should fix some deprecation warnings + under Python 3.10. Thanks to Karthikeyan Singaravelan for the report, + ``@Narendra-Neerukonda`` for the patch, and to Thomas Grainger and Jun Omae + for patch workshopping. +- :feature:`1951` Add SSH config token expansion (eg ``%h``, ``%p``) when + parsing ``ProxyJump`` directives. Patch courtesy of Bruno Inec. +- :bug:`1964` (via :issue:`2024` as also reported in :issue:`2023`) + `~paramiko.pkey.PKey` instances' ``__eq__`` did not have the usual safety + guard in place to ensure they were being compared to another ``PKey`` object, + causing occasional spurious ``BadHostKeyException`` (among other things). + This has been fixed. Thanks to Shengdun Hua for the original report/patch and + to Christopher Papke for the final version of the fix. +- :support:`2004` (via :issue:`2011`) Apply unittest ``skipIf`` to tests + currently using SHA1 in their critical path, to avoid failures on systems + starting to disable SHA1 outright in their crypto backends (eg RHEL 9). + Report & patch via Paul Howarth. +- :bug:`2035` Servers offering certificate variants of hostkey algorithms (eg + ``ssh-rsa-cert-v01@openssh.com``) could not have their host keys verified by + Paramiko clients, as it only ever considered non-cert key types for that part + of connection handshaking. This has been fixed. +- :release:`2.10.3 <2022-03-18>` +- :release:`2.9.3 <2022-03-18>` +- :bug:`1963` (via :issue:`1977`) Certificate-based pubkey auth was + inadvertently broken when adding SHA2 support; this has been fixed. Reported + by Erik Forsberg and fixed by Jun Omae. +- :bug:`2002` (via :issue:`2003`) Switch from module-global to thread-local + storage when recording thread IDs for a logging helper; this should avoid one + flavor of memory leak for long-running processes. Catch & patch via Richard + Kojedzinszky. +- :release:`2.10.2 <2022-03-14>` +- :bug:`2001` Fix Python 2 compatibility breakage introduced in 2.10.1. Spotted + by Christian Hammond. + + .. warning:: + This is almost certainly the last time we will fix Python 2 related + errors! Please see `the roadmap + `_. + +- :release:`2.10.1 <2022-03-11>` +- :bug:`- (2.10+)` (`CVE-2022-24302 + `_) Creation + of new private key files using `~paramiko.pkey.PKey` subclasses was subject + to a race condition between file creation & mode modification, which could be + exploited by an attacker with knowledge of where the Paramiko-using code + would write out such files. + + This has been patched by using `os.open` and `os.fdopen` to ensure new files + are opened with the correct mode immediately. We've left the subsequent + explicit ``chmod`` in place to minimize any possible disruption, though it + may get removed in future backwards-incompatible updates. + + Thanks to Jan Schejbal for the report & feedback on the solution, and to + Jeremy Katz at Tidelift for coordinating the disclosure. +- :release:`2.10.0 <2022-03-11>` +- :feature:`1976` Add support for the ``%C`` token when parsing SSH config + files. Foundational PR submitted by ``@jbrand42``. +- :feature:`1509` (via :issue:`1868`, :issue:`1837`) Add support for OpenSSH's + Windows agent as a fallback when Putty/WinPageant isn't available or + functional. Reported by ``@benj56`` with patches/PRs from ``@lewgordon`` and + Patrick Spendrin. +- :bug:`892 major` Significantly speed up low-level read/write actions on + `~paramiko.sftp_file.SFTPFile` objects by using `bytearray`/`memoryview`. + This is unlikely to change anything for users of the higher level methods + like `SFTPClient.get ` or + `SFTPClient.getfo `, but users of + `SFTPClient.open ` will likely see + orders of magnitude improvements for files larger than a few megabytes in + size. + + Thanks to ``@jkji`` for the original report and to Sevastian Tchernov for the + patch. +- :support:`1985` Add ``six`` explicitly to install-requires; it snuck into + active use at some point but has only been indicated by transitive dependency + on ``bcrypt`` until they somewhat-recently dropped it. This will be + short-lived until we `drop Python 2 + support `_. Thanks to Sondre + Lillebø Gundersen for catch & patch. +- :release:`2.9.2 <2022-01-08>` +- :bug:`-` Connecting to servers which support ``server-sig-algs`` but which + have no overlap between that list and what a Paramiko client supports, now + raise an exception instead of defaulting to ``rsa-sha2-512`` (since the use + of ``server-sig-algs`` allows us to know what the server supports). +- :bug:`-` Enhanced log output when connecting to servers that do not support + ``server-sig-algs`` extensions, making the new-as-of-2.9 defaulting to SHA2 + pubkey algorithms more obvious when it kicks in. +- :release:`2.9.1 <2021-12-24>` +- :bug:`1955` Server-side support for ``rsa-sha2-256`` and ``ssh-rsa`` wasn't + fully operable after 2.9.0's release (signatures for RSA pubkeys were always + run through ``rsa-sha2-512`` instead). Report and early stab at a fix + courtesy of Jun Omae. +- :release:`2.9.0 <2021-12-23>` +- :feature:`1643` (also :issue:`1925`, :issue:`1644`, :issue:`1326`) Add + support for SHA-2 variants of RSA key verification algorithms (as described + in :rfc:`8332`) as well as limited SSH extension negotiation (:rfc:`8308`). + + .. warning:: + This change is slightly backwards incompatible, insofar as action is + required if your target systems do not support either RSA2 or the + ``server-sig-algs`` protocol extension. + + Specifically, you need to specify ``disabled_algorithms={'keys': + ['rsa-sha2-256', 'rsa-sha2-512']}`` in either `SSHClient + ` or `Transport + `. See below for details on why. + + How SSH servers/clients decide when and how to use this functionality can be + complicated; Paramiko's support is as follows: + + - Client verification of server host key during key exchange will now prefer + ``rsa-sha2-512``, ``rsa-sha2-256``, and legacy ``ssh-rsa`` algorithms, in + that order, instead of just ``ssh-rsa``. + + - Note that the preference order of other algorithm families such as + ``ed25519`` and ``ecdsa`` has not changed; for example, those two + groups are still preferred over RSA. + + - Server mode will now offer all 3 RSA algorithms for host key verification + during key exchange, similar to client mode, if it has been configured with + an RSA host key. + - Client mode key exchange now sends the ``ext-info-c`` flag signaling + support for ``MSG_EXT_INFO``, and support for parsing the latter + (specifically, its ``server-sig-algs`` flag) has been added. + - Client mode, when performing public key authentication with an RSA key or + cert, will act as follows: + + - In all cases, the list of algorithms to consider is based on the new + ``preferred_pubkeys`` list (see below) and ``disabled_algorithms`` + (specifically, its ``pubkeys`` key); this list, like with host keys, + prefers SHA2-512, SHA2-256 and SHA1, in that order. + - When the server does not send ``server-sig-algs``, Paramiko will attempt + the first algorithm in the above list. Clients connecting to legacy + servers should thus use ``disabled_algorithms`` to turn off SHA2. + - When the server does send ``server-sig-algs``, the first algorithm + supported by both ends is used, or if there is none, it falls back to the + previous behavior. + + - SSH agent support grew the ability to specify algorithm flags when + requesting private key signatures; this is now used to forward SHA2 + algorithms when appropriate. + - Server mode is now capable of pubkey auth involving SHA-2 signatures from + clients, provided one's server implementation actually provides for doing + so. + + - This includes basic support for sending ``MSG_EXT_INFO`` (containing + ``server-sig-algs`` only) to clients advertising ``ext-info-c`` in their + key exchange list. + + In order to implement the above, the following API additions were made: + + - `PKey.sign_ssh_data `: Grew an extra, optional + ``algorithm`` keyword argument (defaulting to ``None`` for most subclasses, + and to ``"ssh-rsa"`` for `~paramiko.rsakey.RSAKey`). + - A new `~paramiko.ssh_exception.SSHException` subclass was added, + `~paramiko.ssh_exception.IncompatiblePeer`, and is raised in all spots + where key exchange aborts due to algorithmic incompatibility. + + - Like all other exceptions in that module, it inherits from + ``SSHException``, and as we did not change anything else about the + raising (i.e. the attributes and message text are the same) this change + is backwards compatible. + + - `~paramiko.transport.Transport` grew a ``_preferred_pubkeys`` attribute and + matching ``preferred_pubkeys`` property to match the other, kex-focused, + such members. This allows client pubkey authentication to honor the + ``disabled_algorithms`` feature. + + Thanks to Krisztián Kovács for the report and an early stab at a patch, as + well as the numerous users who submitted feedback on the issue, including but + not limited to: Christopher Rabotin, Sam Bull, and Manfred Kaiser. + +- :release:`2.8.1 <2021-11-28>` +- :bug:`985` (via :issue:`992`) Fix listdir failure when server uses a locale. + Now on Python 2.7 `SFTPAttributes ` will + decode abbreviated month names correctly rather than raise + ``UnicodeDecodeError```. Patch courtesy of Martin Packman. +- :bug:`1024` Deleting items from `~paramiko.hostkeys.HostKeys` would + incorrectly raise `KeyError` even for valid keys, due to a logic bug. This + has been fixed. Report & patch credit: Jia Zhang. +- :bug:`1257` (also :issue:`1266`) Update RSA and ECDSA key decoding + subroutines to correctly catch exception types thrown by modern + versions of Cryptography (specifically ``TypeError`` and + its internal ``UnsupportedAlgorithm``). These exception classes will now + become `~paramiko.ssh_exception.SSHException` instances instead of bubbling + up. Thanks to Ignat Semenov for the report and ``@tylergarcianet`` for an + early patch. +- :bug:`-` (also :issue:`908`) Update `~paramiko.pkey.PKey` and subclasses to + compare (``__eq__``) via direct field/attribute comparison instead of hashing + (while retaining the existing behavior of ``__hash__`` via a slight + refactor). Big thanks to Josh Snyder and Jun Omae for the reports, and to + Josh Snyder for reproduction details & patch. + + .. warning:: + This fixes a security flaw! If you are running Paramiko on 32-bit systems + with low entropy (such as any 32-bit Python 2, or a 32-bit Python 3 which + is running with ``PYTHONHASHSEED=0``) it is possible for an attacker to + craft a new keypair from an exfiltrated public key, which Paramiko would + consider equal to the original key. + + This could enable attacks such as, but not limited to, the following: + + - Paramiko server processes would incorrectly authenticate the attacker + (using their generated private key) as if they were the victim. We see + this as the most plausible attack using this flaw. + - Paramiko client processes would incorrectly validate a connected server + (when host key verification is enabled) while subjected + to a man-in-the-middle attack. This impacts more users than the + server-side version, but also carries higher requirements for the + attacker, namely successful DNS poisoning or other MITM techniques. + +- :release:`2.8.0 <2021-10-09>` +- :support:`-` Administrivia overhaul, including but not limited to: + + - Migrate CI to CircleCI + - Primary dev branch is now ``main`` (renamed) + - Many README edits for clarity, modernization etc; including a bunch more + (and consistent) status badges & unification with main project site index + - PyPI page much more fleshed out (long_description is now filled in with the + README; sidebar links expanded; etc) + - flake8, pytest configs split out of setup.cfg into their own files + - Invoke/invocations (used by maintainers/contributors) upgraded to modern + versions + +- :bug:`1462 major` (via :issue:`1882`) Newer server-side key exchange + algorithms not intended to use SHA1 (``diffie-hellman-group14-sha256``, + ``diffie-hellman-group16-sha512``) were incorrectly using SHA1 after all, due + to a bug causing them to ignore the ``hash_algo`` class attribute. This has + been corrected. Big thanks to ``@miverson`` for the report and to Benno Rice + for the patch. +- :feature:`1846` Add a ``prefetch`` keyword argument to `SFTPClient.get `/`SFTPClient.getfo ` + so users who need to skip SFTP prefetching are able to conditionally turn it + off. Thanks to Github user ``@h3ll0r`` for the PR. +- :release:`2.7.2 <2020-08-30>` +- :support:`- backported` Update our CI to catch issues with sdist generation, + installation and testing. +- :support:`1727 backported` Add missing test suite fixtures directory to + MANIFEST.in, reinstating the ability to run Paramiko's tests from an sdist + tarball. Thanks to Sandro Tosi for reporting the issue and to Blazej Michalik + for the PR. +- :support:`1722 backported` Remove leading whitespace from OpenSSH RSA test + suite static key fixture, to conform better to spec. Credit: Alex Gaynor. +- :bug:`-` Fix incorrect string formatting causing unhelpful error message + annotation when using Kerberos/GSSAPI. (Thanks, newer version of flake8!) +- :bug:`1723` Fix incorrectly swapped order of ``p`` and ``q`` numbers when + loading OpenSSH-format RSA private keys. At minimum this should address a + slowdown when using such keys, and it also means Paramiko works with + Cryptography 3.1 and above (which complains strenuously when this problem + appears). Thanks to Alex Gaynor for the patch. +- :release:`2.7.1 <2019-12-09>` +- :bug:`1567` The new-style private key format (added in 2.7) suffered from an + unpadding bug which had been fixed earlier for Ed25519 (as that key type has + always used the newer format). That fix has been refactored and applied to + the base key class, courtesy of Pierce Lopez. +- :bug:`1565` (via :issue:`1566`) Fix a bug in support for ECDSA keys under the + newly supported OpenSSH key format. Thanks to Pierce Lopez for the patch. +- :release:`2.7.0 <2019-12-03>` +- :feature:`602` (via :issue:`1343`, :issue:`1313`, :issue:`618`) Implement + support for OpenSSH 6.5-style private key files (typically denoted as having + ``BEGIN OPENSSH PRIVATE KEY`` headers instead of PEM format's ``BEGIN RSA + PRIVATE KEY`` or similar). If you were getting any sort of weird auth error + from "modern" keys generated on newer operating system releases (such as + macOS Mojave), this is the first update to try. + + Major thanks to everyone who contributed or tested versions of the patch, + including but not limited to: Kevin Abel, Michiel Tiller, Pierce Lopez, and + Jared Hobbs. +- :bug:`- major` ``ssh_config`` :ref:`token expansion ` used a + different method of determining the local username (``$USER`` env var), + compared to what the (much older) client connection code does + (``getpass.getuser``, which includes ``$USER`` but may check other variables + first, and is generally much more comprehensive). Both modules now use + ``getpass.getuser``. +- :feature:`-` A couple of outright `~paramiko.config.SSHConfig` parse errors + were previously represented as vanilla ``Exception`` instances; as part of + recent feature work a more specific exception class, + `~paramiko.ssh_exception.ConfigParseError`, has been created. It is now also + used in those older spots, which is naturally backwards compatible. +- :feature:`717` Implement support for the ``Match`` keyword in ``ssh_config`` + files. Previously, this keyword was simply ignored & keywords inside such + blocks were treated as if they were part of the previous block. Thanks to + Michael Leinartas for the initial patchset. + + .. note:: + This feature adds a new :doc:`optional install dependency `, + `Invoke `_, for managing ``Match exec`` + subprocesses. + +- :support:`-` Additional :doc:`installation ` ``extras_require`` + "flavors" (``ed25519``, ``invoke``, and ``all``) have been added to + our packaging metadata; see the install docs for details. +- :bug:`- major` Paramiko's use of ``subprocess`` for ``ProxyCommand`` support + is conditionally imported to prevent issues on limited interpreter platforms + like Google Compute Engine. However, any resulting ``ImportError`` was lost + instead of preserved for raising (in the rare cases where a user tried + leveraging ``ProxyCommand`` in such an environment). This has been fixed. +- :bug:`- major` Perform deduplication of ``IdentityFile`` contents during + ``ssh_config`` parsing; previously, if your config would result in the same + value being encountered more than once, ``IdentityFile`` would contain that + many copies of the same string. +- :feature:`897` Implement most 'canonical hostname' ``ssh_config`` + functionality (``CanonicalizeHostname``, ``CanonicalDomains``, + ``CanonicalizeFallbackLocal``, and ``CanonicalizeMaxDots``; + ``CanonicalizePermittedCNAMEs`` has **not** yet been implemented). All were + previously silently ignored. Reported by Michael Leinartas. +- :support:`-` Explicitly document :ref:`which ssh_config features we + currently support `. Previously users just had to guess, + which is simply no good. +- :feature:`-` Add new convenience classmethod constructors to + `~paramiko.config.SSHConfig`: `~paramiko.config.SSHConfig.from_text`, + `~paramiko.config.SSHConfig.from_file`, and + `~paramiko.config.SSHConfig.from_path`. No more annoying two-step process! +- :release:`2.6.0 <2019-06-23>` +- :feature:`1463` Add a new keyword argument to `SSHClient.connect + ` and `~paramiko.transport.Transport`, + ``disabled_algorithms``, which allows selectively disabling one or more + kex/key/cipher/etc algorithms. This can be useful when disabling algorithms + your target server (or client) does not support cleanly, or to work around + unpatched bugs in Paramiko's own implementation thereof. +- :release:`2.5.1 <2019-06-23>` +- :release:`2.4.3 <2019-06-23>` +- :bug:`1306` (via :issue:`1400`) Fix Ed25519 key handling so certain key + comment lengths don't cause ``SSHException("Invalid key")`` (this was + technically a bug in how padding, or lack thereof, is + calculated/interpreted). Thanks to ``@parke`` for the bug report & Pierce + Lopez for the patch. +- :support:`1440` (with initial fixes via :issue:`1460`) Tweak many exception + classes so their string representations are more human-friendly; this also + includes incidental changes to some ``super()`` calls. + + The definitions of exceptions' ``__init__`` methods have *not* changed, nor + have any log messages been altered, so this should be backwards compatible + for everything except the actual exceptions' ``__str__()`` outputs. + + Thanks to Fabian Büchler for original report & Pierce Lopez for the + foundational patch. +- :support:`1311` (for :issue:`584`, replacing :issue:`1166`) Add + backwards-compatible support for the ``gssapi`` GSSAPI library, as the + previous backend (``python-gssapi``) has since become defunct. This change + also includes tests for the GSSAPI functionality. + + Big thanks to Anselm Kruis for the patch and to Sebastian Deiß (author of our + initial GSSAPI functionality) for review. + + .. note:: + This feature also adds ``setup.py`` 'extras' support for installing + Paramiko as ``paramiko[gssapi]``, which pulls in the optional + dependencies you had to get by hand previously. + + .. note:: + To be very clear, this patch **does not** remove support for the older + ``python-gssapi`` library. We *may* remove that support in a later release, + but for now, either library will work. Please upgrade to ``gssapi`` when + you can, however, as ``python-gssapi`` is no longer maintained upstream. + +- :bug:`322 major` `SSHClient.exec_command + ` previously returned a naive + `~paramiko.channel.ChannelFile` object for its ``stdin`` value; such objects + don't know to properly shut down the remote end's stdin when they + ``.close()``. This lead to issues (such as hangs) when running remote + commands that read from stdin. + + A new subclass, `~paramiko.channel.ChannelStdinFile`, has been created which + closes remote stdin when it itself is closed. + `~paramiko.client.SSHClient.exec_command` has been updated to use that class + for its ``stdin`` return value. + + Thanks to Brandon Rhodes for the report & steps to reproduce. +- :release:`2.5.0 <2019-06-09>` +- :feature:`1233` (also :issue:`1229`, :issue:`1332`) Add support for + encrypt-then-MAC (ETM) schemes (``hmac-sha2-256-etm@openssh.com``, + ``hmac-sha2-512-etm@openssh.com``) and two newer Diffie-Hellman group key + exchange algorithms (``group14``, using SHA256; and ``group16``, using + SHA512). Patch courtesy of Edgar Sousa. +- :feature:`532` (via :issue:`1384` and :issue:`1258`) Add support for + Curve25519 key exchange (aka ``curve25519-sha256@libssh.org``). Thanks to + Alex Gaynor and Dan Fuhry for supplying patches. +- :support:`1379` (also :issue:`1369`) Raise Cryptography dependency + requirement to version 2.5 (from 1.5) and update some deprecated uses of its + API. + + This removes a bunch of warnings of the style + ``CryptographyDeprecationWarning: encode_point has been deprecated on + EllipticCurvePublicNumbers and will be removed in a future version. Please + use EllipticCurvePublicKey.public_bytes to obtain both compressed and + uncompressed point encoding`` and similar, which users who had eventually + upgraded to Cryptography 2.x would encounter. + + .. warning:: + This change is backwards incompatible **if** you are unable to upgrade your + version of Cryptography. Please see `Cryptography's own changelog + `_ for details on what may + change when you upgrade; for the most part the only changes involved + dropping older Python versions (such as 2.6, 3.3, or some PyPy editions) + which Paramiko itself has already dropped. + +- :support:`1378 backported` Add support for the modern (as of Python 3.3) + import location of ``MutableMapping`` (used in host key management) to avoid + the old location becoming deprecated in Python 3.8. Thanks to Josh Karpel for + catch & patch. +- :release:`2.4.2 <2018-09-18>` +- :release:`2.3.3 <2018-09-18>` +- :release:`2.2.4 <2018-09-18>` +- :release:`2.1.6 <2018-09-18>` +- :release:`2.0.9 <2018-09-18>` +- :bug:`-` Modify protocol message handling such that ``Transport`` does not + respond to ``MSG_UNIMPLEMENTED`` with its own ``MSG_UNIMPLEMENTED``. This + behavior probably didn't cause any outright errors, but it doesn't seem to + conform to the RFCs and could cause (non-infinite) feedback loops in some + scenarios (usually those involving Paramiko on both ends). +- :bug:`1283` Fix exploit (CVE-2018-1000805) in Paramiko's server mode (**not** + client mode) where hostile clients could trick the server into thinking they + were authenticated without actually submitting valid authentication. + + Specifically, steps have been taken to start separating client and server + related message types in the message handling tables within ``Transport`` and + ``AuthHandler``; this work is not complete but enough has been performed to + close off this particular exploit (which was the only obvious such exploit + for this particular channel). + + Thanks to Daniel Hoffman for the detailed report. +- :support:`1292 backported (<2.4)` Backport changes from :issue:`979` (added + in Paramiko + 2.3) to Paramiko 2.0-2.2, using duck-typing to preserve backwards + compatibility. This allows these older versions to use newer Cryptography + sign/verify APIs when available, without requiring them (as is the case with + Paramiko 2.3+). + + Practically speaking, this change prevents spamming of + ``CryptographyDeprecationWarning`` notices which pop up in the above scenario + (older Paramiko, newer Cryptography). + + .. note:: + This is a no-op for Paramiko 2.3+, which have required newer Cryptography + releases since they were released. + +- :support:`1291 backported (<2.4)` Backport pytest support and application of + the ``black`` code formatter (both of which previously only existed in the + 2.4 branch and above) to everything 2.0 and newer. This makes back/forward + porting bugfixes significantly easier. +- :support:`1262 backported` Add ``*.pub`` files to the MANIFEST so distributed + source packages contain some necessary test assets. Credit: Alexander + Kapshuna. +- :feature:`1212` Updated `SSHConfig.lookup ` + so it returns a new, type-casting-friendly dict subclass + (`~paramiko.config.SSHConfigDict`) in lieu of dict literals. This ought to be + backwards compatible, and allows an easier way to check boolean or int type + ``ssh_config`` values. Thanks to Chris Rose for the patch. +- :support:`1191` Update our install docs with (somewhat) recently added + additional dependencies; we previously only required Cryptography, but the + docs never got updated after we incurred ``bcrypt`` and ``pynacl`` + requirements for Ed25519 key support. + + Additionally, ``pyasn1`` was never actually hard-required; it was necessary + during a development branch, and is used by the optional GSSAPI support, but + is not required for regular installation. Thus, it has been removed from our + ``setup.py`` and its imports in the GSSAPI code made optional. + + Credit to ``@stevenwinfield`` for highlighting the outdated install docs. +- :release:`2.4.1 <2018-03-12>` +- :release:`2.3.2 <2018-03-12>` +- :release:`2.2.3 <2018-03-12>` +- :release:`2.1.5 <2018-03-12>` +- :release:`2.0.8 <2018-03-12>` +- :release:`1.18.5 <2018-03-12>` +- :release:`1.17.6 <2018-03-12>` +- :bug:`1175 (1.17+)` Fix a security flaw (CVE-2018-7750) in Paramiko's server + mode (emphasis on **server** mode; this does **not** impact *client* use!) + where authentication status was not checked before processing channel-open + and other requests typically only sent after authenticating. Big thanks to + Matthijs Kooijman for the report. +- :bug:`1168` Add newer key classes for Ed25519 and ECDSA to + ``paramiko.__all__`` so that code introspecting that attribute, or using + ``from paramiko import *`` (such as some IDEs) sees them. Thanks to + ``@patriksevallius`` for the patch. +- :bug:`1039` Ed25519 auth key decryption raised an unexpected exception when + given a unicode password string (typical in python 3). Report by Theodor van + Nahl and fix by Pierce Lopez. +- :release:`2.4.0 <2017-11-14>` +- :feature:`-` Add a new ``passphrase`` kwarg to `SSHClient.connect + ` so users may disambiguate key-decryption + passphrases from password-auth passwords. (This is a backwards compatible + change; ``password`` will still pull double duty as a passphrase when + ``passphrase`` is not given.) +- :support:`-` Update ``tearDown`` of client test suite to avoid hangs due to + eternally blocking ``accept()`` calls on the internal server thread (which + can occur when test code raises an exception before actually connecting to + the server.) +- :bug:`1108 (1.17+)` Rename a private method keyword argument (which was named + ``async``) so that we're compatible with the upcoming Python 3.7 release + (where ``async`` is a new keyword.) Thanks to ``@vEpiphyte`` for the report. +- :support:`1100` Updated the test suite & related docs/metadata/config to be + compatible with pytest instead of using the old, custom, crufty + unittest-based ``test.py``. + + This includes marking known-slow tests (mostly the SFTP ones) so they can be + filtered out by ``inv test``'s default behavior; as well as other minor + tweaks to test collection and/or display (for example, GSSAPI tests are + collected, but skipped, instead of not even being collected by default as in + ``test.py``.) +- :support:`- backported` Include LICENSE file in wheel archives. +- :support:`1070` Drop Python 2.6 and Python 3.3 support; now only 2.7 and 3.4+ + are supported. If you're unable to upgrade from 2.6 or 3.3, please stick to + the Paramiko 2.3.x (or below) release lines. +- :release:`2.3.1 <2017-09-22>` +- :bug:`1071` Certificate support broke the no-certificate case for Ed25519 + keys (symptom is an ``AttributeError`` about ``public_blob``.) This went + uncaught due to cert autoload behavior (i.e. our test suite never actually + ran the no-cert case, because the cert existed!) Both issues have been fixed. + Thanks to John Hu for the report. +- :release:`2.3.0 <2017-09-18>` +- :release:`2.2.2 <2017-09-18>` +- :release:`2.1.4 <2017-09-18>` +- :release:`2.0.7 <2017-09-18>` +- :release:`1.18.4 <2017-09-18>` +- :bug:`1065` Add rekeying support to GSSAPI connections, which was erroneously + missing. Without this fix, any attempt to renegotiate the transport keys for + a ``gss-kex``-authed `~paramiko.transport.Transport` would cause a MIC + failure and terminate the connection. Thanks to Sebastian Deiß and Anselm + Kruis for the patch. +- :feature:`1063` Add a ``gss_trust_dns`` option to ``Client`` and + ``Transport`` to allow explicitly setting whether or not DNS canonicalization + should occur when using GSSAPI. Thanks to Richard E. Silverman for the report + & Sebastian Deiß for initial patchset. +- :bug:`1061` Clean up GSSAPI authentication procedures so they do not prevent + normal fallback to other authentication methods on failure. (In other words, + presence of GSSAPI functionality on a target server precluded use of _any_ + other auth type if the user was unable to pass GSSAPI auth.) Patch via Anselm + Kruis. +- :bug:`1060` Fix key exchange (kex) algorithm list for GSSAPI authentication; + previously, the list used solely out-of-date algorithms, and now contains + newer ones listed preferentially before the old. Credit: Anselm Kruis. +- :bug:`1055 (1.17+)` (also :issue:`1056`, :issue:`1057`, :issue:`1058`, + :issue:`1059`) Fix up host-key checking in our GSSAPI support, which was + previously using an incorrect API call. Thanks to Anselm Kruis for the + patches. +- :bug:`945 (1.18+)` (backport of :issue:`910` and re: :issue:`865`) SSHClient + now requests the type of host key it has (e.g. from known_hosts) and does not + consider a different type to be a "Missing" host key. This fixes a common + case where an ECDSA key is in known_hosts and the server also has an RSA host + key. Thanks to Pierce Lopez. +- :support:`979` Update how we use `Cryptography `_'s + signature/verification methods so we aren't relying on a deprecated API. + Thanks to Paul Kehrer for the patch. + + .. warning:: + This bumps the minimum Cryptography version from 1.1 to 1.5. Such an + upgrade should be backwards compatible and easy to do. See `their changelog + `_ for additional details. +- :support:`-` Ed25519 keys never got proper API documentation support; this + has been fixed. +- :feature:`1026` Update `~paramiko.ed25519key.Ed25519Key` so its constructor + offers the same ``file_obj`` parameter as its sibling key classes. Credit: + Michal Kuffa. +- :feature:`1013` Added pre-authentication banner support for the server + interface (`ServerInterface.get_banner + ` plus related support in + ``Transport/AuthHandler``.) Patch courtesy of Dennis Kaarsemaker. +- :bug:`60 major` (via :issue:`1037`) Paramiko originally defaulted to zlib + compression level 9 (when one connects with ``compression=True``; it defaults + to off.) This has been found to be quite wasteful and tends to cause much + longer transfers in most cases, than is necessary. + + OpenSSH defaults to compression level 6, which is a much more reasonable + setting (nearly identical compression characteristics but noticeably, + sometimes significantly, faster transmission); Paramiko now uses this value + instead. + + Thanks to Damien Dubé for the report and ``@DrNeutron`` for investigating & + submitting the patch. +- :support:`-` Display exception type and message when logging auth-rejection + messages (ones reading ``Auth rejected: unsupported or mangled public key``); + previously this error case had a bare except and did not display exactly why + the key failed. It will now append info such as ``KeyError: + 'some-unknown-type-string'`` or similar. +- :feature:`1042` (also partially :issue:`531`) Implement basic client-side + certificate authentication (as per the OpenSSH vendor extension.) + + The core implementation is `PKey.load_certificate + ` and its corresponding ``.public_blob`` + attribute on key objects, which is honored in the auth and transport modules. + Additionally, `SSHClient.connect ` will + now automatically load certificate data alongside private key data when one + has appropriately-named cert files (e.g. ``id_rsa-cert.pub``) - see its + docstring for details. + + Thanks to Jason Rigby for a first draft (:issue:`531`) and to Paul Kapp for + the second draft, upon which the current functionality has been based (with + modifications.) + + .. note:: + This support is client-focused; Paramiko-driven server code is capable of + handling cert-bearing pubkey auth packets, *but* it does not interpret any + cert-specific fields, so the end result is functionally identical to a + vanilla pubkey auth process (and thus requires e.g. prepopulated + authorized-keys data.) We expect full server-side cert support to follow + later. + +- :support:`1041` Modify logic around explicit disconnect + messages, and unknown-channel situations, so that they rely on centralized + shutdown code instead of running their own. This is at worst removing some + unnecessary code, and may help with some situations where Paramiko hangs at + the end of a session. Thanks to Paul Kapp for the patch. +- :support:`1012` (via :issue:`1016`) Enhance documentation around the new + `SFTP.posix_rename ` method so + it's referenced in the 'standard' ``rename`` method for increased visibility. + Thanks to Marius Flage for the report. +- :release:`2.2.1 <2017-06-13>` +- :bug:`993` Ed25519 host keys were not comparable/hashable, causing an + exception if such a key existed in a ``known_hosts`` file. Thanks to Oleh + Prypin for the report and Pierce Lopez for the fix. +- :bug:`990` The (added in 2.2.0) ``bcrypt`` dependency should have been on + version 3.1.3 or greater (was initially set to 3.0.0 or greater.) Thanks to + Paul Howarth for the report. +- :release:`2.2.0 <2017-06-09>` +- :release:`2.1.3 <2017-06-09>` +- :release:`2.0.6 <2017-06-09>` +- :release:`1.18.3 <2017-06-09>` +- :release:`1.17.5 <2017-06-09>` +- :bug:`865` SSHClient now requests the type of host key it has (e.g. from + known_hosts) and does not consider a different type to be a "Missing" host + key. This fixes a common case where an ECDSA key is in known_hosts and the + server also has an RSA host key. Thanks to Pierce Lopez. +- :support:`906 (1.18+)` Clean up a handful of outdated imports and related + tweaks. Thanks to Pierce Lopez. +- :bug:`984` Enhance default cipher preference order such that + ``aes(192|256)-cbc`` are preferred over ``blowfish-cbc``. Thanks to Alex + Gaynor. +- :bug:`971 (1.17+)` Allow any type implementing the buffer API to be used with + `BufferedFile `, `Channel + `, and `SFTPFile `. + This resolves a regression introduced in 1.13 with the Python 3 porting + changes, when using types such as ``memoryview``. Credit: Martin Packman. +- :bug:`741` (also :issue:`809`, :issue:`772`; all via :issue:`912`) Writing + encrypted/password-protected private key files was silently broken since 2.0 + due to an incorrect API call; this has been fixed. + + Includes a directly related fix, namely adding the ability to read + ``AES-256-CBC`` ciphered private keys (which is now what we tend to write out + as it is Cryptography's default private key cipher.) + + Thanks to ``@virlos`` for the original report, Chris Harris and ``@ibuler`` + for initial draft PRs, and ``@jhgorrell`` for the final patch. +- :feature:`65` (via :issue:`471`) Add support for OpenSSH's SFTP + ``posix-rename`` protocol extension (section 3.3 of `OpenSSH's protocol + extension document + `_), + via a new ``posix_rename`` method in `SFTPClient + ` and `SFTPServerInterface + `. Thanks to Wren Turkal + for the initial patch & Mika Pflüger for the enhanced, merged PR. +- :feature:`869` Add an ``auth_timeout`` kwarg to `SSHClient.connect + ` (default: 30s) to avoid hangs when the + remote end becomes unresponsive during the authentication step. Credit to + ``@timsavage``. + + .. note:: + This technically changes behavior, insofar as very slow auth steps >30s + will now cause timeout exceptions instead of completing. We doubt most + users will notice; those affected can simply give a higher value to + ``auth_timeout``. + +- :support:`921` Tighten up the ``__hash__`` implementation for various key + classes; less code is good code. Thanks to Francisco Couzo for the patch. +- :support:`956 backported (1.17+)` Switch code coverage service from + coveralls.io to codecov.io (& then disable the latter's auto-comments.) + Thanks to Nikolai Røed Kristiansen for the patch. +- :bug:`983` Move ``sha1`` above the now-arguably-broken ``md5`` in the list of + preferred MAC algorithms, as an incremental security improvement for users + whose target systems offer both. Credit: Pierce Lopez. +- :bug:`667` The RC4/arcfour family of ciphers has been broken since version + 2.0; but since the algorithm is now known to be completely insecure, we are + opting to remove support outright instead of fixing it. Thanks to Alex Gaynor + for catch & patch. +- :feature:`857` Allow `SSHClient.set_missing_host_key_policy + ` to accept policy + classes _or_ instances, instead of only instances, thus fixing a + long-standing gotcha for unaware users. +- :feature:`951` Add support for ECDH key exchange (kex), specifically the + algorithms ``ecdh-sha2-nistp256``, ``ecdh-sha2-nistp384``, and + ``ecdh-sha2-nistp521``. They now come before the older ``diffie-hellman-*`` + family of kex algorithms in the preferred-kex list. Thanks to Shashank + Veerapaneni for the patch & Pierce Lopez for a follow-up. +- :support:`- backported` A big formatting pass to clean up an enormous number + of invalid Sphinx reference links, discovered by switching to a modern, + rigorous nitpicking doc-building mode. +- :bug:`900` (via :issue:`911`) Prefer newer ``ecdsa-sha2-nistp`` keys over RSA + and DSA keys during host key selection. This improves compatibility with + OpenSSH, both in terms of general behavior, and also re: ability to properly + leverage OpenSSH-modified ``known_hosts`` files. Credit: ``@kasdoe`` for + original report/PR and Pierce Lopez for the second draft. +- :bug:`794` (via :issue:`981`) Prior support for ``ecdsa-sha2-nistp(384|521)`` + algorithms didn't fully extend to covering host keys, preventing connection + to hosts which only offer these key types and no others. This is now fixed. + Thanks to ``@ncoult`` and ``@kasdoe`` for reports and Pierce Lopez for the + patch. +- :feature:`325` (via :issue:`972`) Add Ed25519 support, for both host keys + and user authentication. Big thanks to Alex Gaynor for the patch. + + .. note:: + This change adds the ``bcrypt`` and ``pynacl`` Python libraries as + dependencies. No C-level dependencies beyond those previously required (for + Cryptography) have been added. + +- :support:`974 backported` Overhaul the codebase to be PEP-8, etc, compliant + (i.e. passes the maintainer's preferred `flake8 `_ + configuration) and add a ``flake8`` step to the Travis config. Big thanks to + Dorian Pula! +- :bug:`949 (1.17+)` SSHClient and Transport could cause a memory leak if + there's a connection problem or protocol error, even if ``Transport.close()`` + is called. Thanks Kyle Agronick for the discovery and investigation, and + Pierce Lopez for assistance. +- :bug:`683 (1.17+)` Make ``util.log_to_file`` append instead of replace. + Thanks to ``@vlcinsky`` for the report. +- :release:`2.1.2 <2017-02-20>` +- :release:`2.0.5 <2017-02-20>` +- :release:`1.18.2 <2017-02-20>` +- :release:`1.17.4 <2017-02-20>` +- :bug:`853 (1.17+)` Tweak how `RSAKey.__str__ ` + behaves so it doesn't cause ``TypeError`` under Python 3. Thanks to Francisco + Couzo for the report. +- :bug:`862 (1.17+)` (via :issue:`863`) Avoid test suite exceptions on + platforms lacking ``errno.ETIME`` (which seems to be some FreeBSD and some + Windows environments.) Thanks to Sofian Brabez. +- :bug:`44 (1.17+)` (via :issue:`891`) `SSHClient ` + now gives its internal `Transport ` a handle on + itself, preventing garbage collection of the client until the session is + closed. Without this, some code which returns stream or transport objects + without the client that generated them, would result in premature session + closure when the client was GCd. Credit: ``@w31rd0`` for original report, + Omer Anson for the patch. +- :bug:`713 (<2.0)` (via :issue:`714` and :issue:`889`) Don't pass + initialization vectors to PyCrypto when dealing with counter-mode ciphers; + newer PyCrypto versions throw an exception otherwise (older ones simply + ignored this parameter altogether). Thanks to ``@jmh045000`` for report & + patches. +- :bug:`895 (1.17+)` Fix a bug in server-mode concerning multiple interactive + auth steps (which were incorrectly responded to). Thanks to Dennis + Kaarsemaker for catch & patch. +- :support:`866 backported (1.17+)` (also :issue:`838`) Remove an old + test-related file we don't support, and add PyPy to Travis-CI config. Thanks + to Pierce Lopez for the final patch and Pedro Rodrigues for an earlier + edition. +- :release:`2.1.1 <2016-12-12>` +- :release:`2.0.4 <2016-12-12>` +- :release:`1.18.1 <2016-12-12>` +- :bug:`859 (1.18+)` (via :issue:`860`) A tweak to the original patch + implementing :issue:`398` was not fully applied, causing calls to + `~paramiko.client.SSHClient.invoke_shell` to fail with ``AttributeError``. + This has been fixed. Patch credit: Kirk Byers. +- :bug:`-` Accidentally merged the new features from 1.18.0 into the + 2.0.x bugfix-only branch. This included merging a bug in one of those new + features (breaking `~paramiko.client.SSHClient.invoke_shell` with an + ``AttributeError``.) The offending code has been stripped out of the 2.0.x + line (but of course, remains in 2.1.x and above.) +- :bug:`859` (via :issue:`860`) A tweak to the original patch implementing + :issue:`398` was not fully applied, causing calls to + `~paramiko.client.SSHClient.invoke_shell` to fail with ``AttributeError``. + This has been fixed. Patch credit: Kirk Byers. +- :release:`2.1.0 <2016-12-09>` +- :release:`2.0.3 <2016-12-09>` +- :release:`1.18.0 <2016-12-09>` +- :release:`1.17.3 <2016-12-09>` +- :bug:`802 (1.17+)` (via :issue:`804`) Update our vendored Windows API module + to address errors of the form ``AttributeError: 'module' object has no + attribute 'c_ssize_t'``. Credit to Jason R. Coombs. +- :bug:`824 (1.17+)` Fix the implementation of ``PKey.write_private_key_file`` + (this method is only publicly defined on subclasses; the fix was in the + private real implementation) so it passes the correct params to ``open()``. + This bug apparently went unnoticed and unfixed for 12 entire years. Congrats + to John Villalovos for noticing & submitting the patch! +- :support:`801 backported (1.17+)` Skip a Unix-only test when on Windows; + thanks to Gabi Davar. +- :support:`792 backported (1.17+)` Minor updates to the README and demos; + thanks to Alan Yee. +- :feature:`780 (1.18+)` (also :issue:`779`, and may help users affected by + :issue:`520`) Add an optional ``timeout`` parameter to + `Transport.start_client ` (and + feed it the value of the configured connection timeout when used within + `SSHClient `.) This helps prevent situations where + 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 (1.17+)` Add a missing ``.closed`` attribute (plus ``._closed`` + because reasons) to `ProxyCommand ` so the + earlier partial fix for :issue:`520` works in situations where one is + gatewaying via ``ProxyCommand``. +- :bug:`334 (1.17+)` Make the ``subprocess`` import in ``proxy.py`` lazy so + users on platforms without it (such as Google App Engine) can import Paramiko + successfully. (Relatedly, make it easier to tweak an active socket check + timeout [in `Transport `] which was previously + hardcoded.) Credit: Shinya Okano. +- :support:`854 backported (1.17+)` Fix incorrect docstring/param-list for + `Transport.auth_gssapi_keyex + ` so it matches the real + signature. Caught by ``@Score_Under``. +- :bug:`681 (1.17+)` Fix a Python3-specific bug re: the handling of read + buffers when using ``ProxyCommand``. Thanks to Paul Kapp for catch & patch. +- :feature:`398 (1.18+)` Add an ``environment`` dict argument to + `Client.exec_command ` (plus the + lower level `Channel.update_environment + ` and + `Channel.set_environment_variable + ` methods) which + implements the ``env`` SSH message type. This means the remote shell + environment can be set without the use of ``VARNAME=value`` shell tricks, + provided the server's ``AcceptEnv`` lists the variables you need to set. + Thanks to Philip Lorenz for the pull request. +- :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 + (``SSHException``) which would occasionally pop up when using + ``ProxyCommand`` gatewaying. Thanks to ``@Depado`` for the initial report and + Paul Kapp for the fix. +- :bug:`774 (1.16+)` Add a ``_closed`` private attribute to + `~paramiko.channel.Channel` objects so that they continue functioning when + used as proxy sockets under Python 3 (e.g. as ``direct-tcpip`` gateways for + other Paramiko connections.) +- :bug:`758 (1.16+)` Apply type definitions to ``_winapi`` module from + `jaraco.windows `_ 3.6.1. This + 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 + driven threading hangs at end of the Python interpreter session. (Includes a + docs update as well - always make sure to ``.close()`` your clients!) +- :bug:`537 (1.16+)` Fix a bug in `BufferedPipe.set_event + ` which could cause + deadlocks/hangs when one uses `select.select` against + `~paramiko.channel.Channel` objects (or otherwise calls `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 + manner (i.e. ``ProxyCommand none`` continues to appear as a total lack of any + ``proxycommand`` key in parsed config structures). Thanks to Pat Brisbin for + the catch. +- :bug:`676` (via :issue:`677`) Fix a backwards incompatibility issue that + cropped up in `SFTPFile.prefetch ` re: + the 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 ` 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. +- :bug:`716` Fix a Python 3 compatibility issue when handling two-factor + authentication. Thanks to Mateusz Kowalski for the catch & original patch. +- :support:`729 backported (>=1.15,<2.0)` Clean up ``setup.py`` to always use + ``setuptools``, not doing so was a historical artifact from bygone days. + Thanks to Alex Gaynor. +- :bug:`649 major (==1.17)` Update the module in charge of handling SSH moduli + so it's consistent with OpenSSH behavior re: prime number selection. Thanks + to Damien Tournoud for catch & patch. +- :bug:`617` (aka `fabric/fabric#1429 + `_; via :issue:`679`; related: + :issue:`678`, :issue:`685`, :issue:`615` & :issue:`616`) Fix up + `~paramiko.ssh_exception.NoValidConnectionsError` so it pickles correctly, + and fix a related Python 3 compatibility issue. Thanks to Rebecca Schlussel + for the report & Marius Gedminas for the patch. +- :bug:`613` (via :issue:`619`) Update to ``jaraco.windows`` 3.4.1 to fix some + errors related to ``ctypes`` on Windows platforms. Credit to Jason R. Coombs. +- :support:`621 backported (>=1.15,<2.0)` Annotate some public attributes on + `~paramiko.channel.Channel` such as ``.closed``. Thanks to Sergey Vasilyev + for the report. +- :bug:`632` Fix logic bug in the SFTP client's callback-calling functionality; + previously there was a chance the given callback would fire twice at the end + of a transfer. Thanks to ``@ab9-er`` for catch & original patch. +- :support:`612 backported (>=1.15,<2.0)` Identify & work around a race + condition in the test for handshake timeouts, which was causing frequent test + failures for a subset of contributors as well as Travis-CI (usually, but not + always, limited to Python 3.5). Props to Ed Kellett for assistance during + some of the troubleshooting. +- :support:`697 backported (>=1.15,<2.0)` Remove whitespace in our + ``setup.py``'s ``install_requires`` as it triggers occasional bugs in some + versions of ``setuptools``. Thanks to Justin Lecher for catch & original + patch. +- :bug:`499` Strip trailing/leading whitespace from lines when parsing SSH + config files - this brings things in line with OpenSSH behavior. Thanks to + Alfredo Esteban for the original report and Nick Pillitteri for the patch. +- :bug:`652` Fix behavior of ``gssapi-with-mic`` auth requests so they fail + gracefully (allowing followup via other auth methods) instead of raising an + exception. Patch courtesy of ``@jamercee``. +- :feature:`588 (==1.17)` Add missing file-like object methods for + `~paramiko.file.BufferedFile` and `~paramiko.sftp_file.SFTPFile`. Thanks to + Adam Meily for the patch. +- :support:`636 backported (>=1.15,<2.0)` Clean up and enhance the README (and + rename it to ``README.rst`` from just ``README``). Thanks to ``@LucasRMehl``. +- :release:`1.16.0 <2015-11-04>` +- :bug:`194 major` (also :issue:`562`, :issue:`530`, :issue:`576`) Streamline + use of ``stat`` when downloading SFTP files via `SFTPClient.get + `; this avoids triggering bugs in some + off-spec SFTP servers such as IBM Sterling. Thanks to ``@muraleee`` for the + initial report and to Torkil Gustavsen for the patch. +- :feature:`467` (also :issue:`139`, :issue:`412`) Fully enable two-factor + authentication (e.g. when a server requires ``AuthenticationMethods + pubkey,keyboard-interactive``). Thanks to ``@perryjrandall`` for the patch + and to ``@nevins-b`` and Matt Robenolt for additional support. +- :bug:`502 major` Fix 'exec' requests in server mode to use ``get_string`` + instead of ``get_text`` to avoid ``UnicodeDecodeError`` on non-UTF-8 input. + Thanks to Anselm Kruis for the patch & discussion. +- :bug:`401` Fix line number reporting in log output regarding invalid + ``known_hosts`` line entries. Thanks to Dylan Thacker-Smith for catch & + patch. +- :support:`525 backported` Update the vendored Windows API addon to a more + recent edition. Also fixes :issue:`193`, :issue:`488`, :issue:`498`. Thanks + to Jason Coombs. +- :release:`1.15.4 <2015-11-02>` +- :release:`1.14.3 <2015-11-02>` +- :release:`1.13.4 <2015-11-02>` +- :bug:`366` Fix `~paramiko.sftp_attr.SFTPAttributes` so its string + representation doesn't raise exceptions on empty/initialized instances. Patch + by Ulrich Petri. +- :bug:`359` Use correct attribute name when trying to use Python 3's + ``int.bit_length`` method; prior to fix, the Python 2 custom fallback + implementation was always used, even on Python 3. Thanks to Alex Gaynor. +- :support:`594 backported` Correct some post-Python3-port docstrings to + specify ``bytes`` type instead of ``str``. Credit to ``@redixin``. +- :bug:`565` Don't explode with ``IndexError`` when reading private key files + lacking an ``-----END PRIVATE KEY-----`` footer. Patch courtesy of + Prasanna Santhanam. +- :feature:`604` Add support for the ``aes192-ctr`` and ``aes192-cbc`` ciphers. + Thanks to Michiel Tiller for noticing it was as easy as tweaking some key + sizes :D +- :feature:`356` (also :issue:`596`, :issue:`365`, :issue:`341`, :issue:`164`, + :issue:`581`, and a bunch of other duplicates besides) Add support for SHA-2 + based key exchange (kex) algorithm ``diffie-hellman-group-exchange-sha256`` + and (H)MAC algorithms ``hmac-sha2-256`` and ``hmac-sha2-512``. + + This change includes tweaks to debug-level logging regarding + algorithm-selection handshakes; the old all-in-one log line is now multiple + easier-to-read, printed-at-handshake-time log lines. + + Thanks to the many people who submitted patches for this functionality and/or + assisted in testing those patches. That list includes but is not limited to, + and in no particular order: Matthias Witte, Dag Wieers, Ash Berlin, Etienne + Perot, Gert van Dijk, ``@GuyShaanan``, Aaron Bieber, ``@cyphase``, and Eric + Brown. +- :release:`1.15.3 <2015-10-02>` +- :support:`554 backported` Fix inaccuracies in the docstring for the ECDSA key + class. Thanks to Jared Hance for the patch. +- :support:`516 backported` Document `~paramiko.agent.AgentRequestHandler`. + Thanks to ``@toejough`` for report & suggestions. +- :bug:`496 (1.15+)` Fix a handful of small but critical bugs in Paramiko's + GSSAPI support (note: this includes switching from PyCrypo's Random to + `os.urandom`). Thanks to Anselm Kruis for catch & patch. +- :bug:`491` (combines :issue:`62` and :issue:`439`) Implement timeout + functionality to address hangs from dropped network connections and/or failed + handshakes. Credit to ``@vazir`` and ``@dacut`` for the original patches and + to Olle Lundberg for reimplementation. +- :bug:`490` Skip invalid/unparsable lines in ``known_hosts`` files, instead + of raising `~paramiko.ssh_exception.SSHException`. This brings Paramiko's + behavior more in line with OpenSSH, which silently ignores such input. Catch + & patch courtesy of Martin Topholm. +- :bug:`404` Print details when displaying + `~paramiko.ssh_exception.BadHostKeyException` objects (expected vs received + data) instead of just "hey shit broke". Patch credit: Loic Dachary. +- :bug:`469` (also :issue:`488`, :issue:`461` and like a dozen others) Fix a + typo introduced in the 1.15 release which broke WinPageant support. Thanks to + everyone who submitted patches, and to Steve Cohen who was the lucky winner + of the cherry-pick lottery. +- :bug:`353` (via :issue:`482`) Fix a bug introduced in the Python 3 port + which caused ``OverFlowError`` (and other symptoms) in SFTP functionality. + Thanks to ``@dboreham`` for leading the troubleshooting charge, and to + Scott Maxwell for the final patch. +- :support:`582` Fix some old ``setup.py`` related helper code which was + breaking ``bdist_dumb`` on Mac OS X. Thanks to Peter Odding for the patch. +- :bug:`22 major` Try harder to connect to multiple network families (e.g. IPv4 + vs IPv6) in case of connection issues; this helps with problems such as hosts + which resolve both IPv4 and IPv6 addresses but are only listening on IPv4. + Thanks to Dries Desmet for original report and Torsten Landschoff for the + foundational patchset. +- :bug:`402` Check to see if an SSH agent is actually present before trying to + forward it to the remote end. This replaces what was usually a useless + ``TypeError`` with a human-readable + `~paramiko.ssh_exception.AuthenticationException`. Credit to Ken Jordan for + the fix and Yvan Marques for original report. +- :release:`1.15.2 <2014-12-19>` +- :release:`1.14.2 <2014-12-19>` +- :release:`1.13.3 <2014-12-19>` +- :bug:`413` (also :issue:`414`, :issue:`420`, :issue:`454`) Be significantly + smarter about polling & timing behavior when running proxy commands, to avoid + unnecessary (often 100%!) CPU usage. Major thanks to Jason Dunsmore for + report & initial patchset and to Chris Adams & John Morrissey for followup + improvements. +- :bug:`455` Tweak packet size handling to conform better to the OpenSSH RFCs; + this helps address issues with interactive program cursors. Courtesy of Jeff + Quast. +- :bug:`428` Fix an issue in `~paramiko.file.BufferedFile` (primarily used in + the SFTP modules) concerning incorrect behavior by + `~paramiko.file.BufferedFile.readlines` on files whose size exceeds the + buffer size. Thanks to ``@achapp`` for catch & patch. +- :bug:`415` Fix ``ssh_config`` parsing to correctly interpret ``ProxyCommand + none`` as the lack of a proxy command, instead of as a literal command string + of ``"none"``. Thanks to Richard Spiers for the catch & Sean Johnson for the + fix. +- :support:`431 backported` Replace handrolled ``ssh_config`` parsing code with + use of the ``shlex`` module. Thanks to Yan Kalchevskiy. +- :support:`422 backported` Clean up some unused imports. Courtesy of Olle + Lundberg. +- :support:`421 backported` Modernize threading calls to use newer API. Thanks + to Olle Lundberg. +- :support:`419 backported` Modernize a bunch of the codebase internals to + leverage decorators. Props to ``@beckjake`` for realizing we're no longer on + Python 2.2 :D +- :bug:`266` Change numbering of `~paramiko.transport.Transport` channels to + start at 0 instead of 1 for better compatibility with OpenSSH & certain + server implementations which break on 1-indexed channels. Thanks to + ``@egroeper`` for catch & patch. +- :bug:`459` Tighten up agent connection closure behavior to avoid spurious + ``ResourceWarning`` display in some situations. Thanks to ``@tkrapp`` for the + catch. +- :bug:`429` Server-level debug message logging was overlooked during the + Python 3 compatibility update; Python 3 clients attempting to log SSH debug + packets encountered type errors. This is now fixed. Thanks to ``@mjmaenpaa`` + for the catch. +- :bug:`320` Update our win_pageant module to be Python 3 compatible. Thanks to + ``@sherbang`` and ``@adamkerz`` for the patches. +- :release:`1.15.1 <2014-09-22>` +- :bug:`399` SSH agent forwarding (potentially other functionality as + well) would hang due to incorrect values passed into the new window size + arguments for `~paramiko.transport.Transport` (thanks to a botched merge). + This has been corrected. Thanks to Dylan Thacker-Smith for the report & + patch. +- :feature:`167` Add `~paramiko.config.SSHConfig.get_hostnames` for easier + introspection of a loaded SSH config file or object. Courtesy of Søren + Løvborg. +- :release:`1.15.0 <2014-09-18>` +- :support:`393` Replace internal use of PyCrypto's ``SHA.new`` with the + stdlib's ``hashlib.sha1``. Thanks to Alex Gaynor. +- :feature:`267` (also :issue:`250`, :issue:`241`, :issue:`228`) Add GSS-API / + SSPI (e.g. Kerberos) key exchange and authentication support + (:ref:`installation docs here `). Mega thanks to Sebastian Deiß, with + assist by Torsten Landschoff. + + .. note:: + Unix users should be aware that the ``python-gssapi`` library (a + requirement for using this functionality) only appears to support + Python 2.7 and up at this time. + +- :bug:`346 major` Fix an issue in private key files' encryption salts that + could cause tracebacks and file corruption if keys were re-encrypted. Credit + to Xavier Nunn. +- :feature:`362` Allow users to control the SSH banner timeout. Thanks to Cory + Benfield. +- :feature:`372` Update default window & packet sizes to more closely adhere to + the pertinent RFC; also expose these settings in the public API so they may + be overridden by client code. This should address some general speed issues + such as :issue:`175`. Big thanks to Olle Lundberg for the update. +- :bug:`373 major` Attempt to fix a handful of issues (such as :issue:`354`) + related to infinite loops and threading deadlocks. Thanks to Olle Lundberg as + well as a handful of community members who provided advice & feedback via + IRC. +- :support:`374` (also :issue:`375`) Old code cleanup courtesy of Olle + Lundberg. +- :support:`377` Factor `~paramiko.channel.Channel` openness sanity check into + a decorator. Thanks to Olle Lundberg for original patch. +- :bug:`298 major` Don't perform point validation on ECDSA keys in + ``known_hosts`` files, since a) this can cause significant slowdown when such + keys exist, and b) ``known_hosts`` files are implicitly trustworthy. Thanks + to Kieran Spear for catch & patch. + + .. note:: + This change bumps up the version requirement for the ``ecdsa`` library to + ``0.11``. + +- :bug:`234 major` Lower logging levels for a few overly-noisy log messages + about secure channels. Thanks to David Pursehouse for noticing & contributing + the fix. +- :feature:`218` Add support for ECDSA private keys on the client side. Thanks + to ``@aszlig`` for the patch. +- :bug:`335 major` Fix ECDSA key generation (generation of brand new ECDSA keys + was broken previously). Thanks to ``@solarw`` for catch & patch. +- :feature:`184` Support quoted values in SSH config file parsing. Credit to + Yan Kalchevskiy. +- :feature:`131` Add a `~paramiko.sftp_client.SFTPClient.listdir_iter` method + to `~paramiko.sftp_client.SFTPClient` allowing for more efficient, + async/generator based file listings. Thanks to John Begeman. +- :support:`378 backported` Minor code cleanup in the SSH config module + courtesy of Olle Lundberg. +- :support:`249 backported` Consolidate version information into one spot. + Thanks to Gabi Davar for the reminder. +- :release:`1.14.1 <2014-08-25>` +- :release:`1.13.2 <2014-08-25>` +- :bug:`376` Be less aggressive about expanding variables in ``ssh_config`` + files, which results in a speedup of SSH config parsing. Credit to Olle + Lundberg. +- :support:`324 backported` A bevvy of documentation typo fixes, courtesy of Roy + Wellington. +- :bug:`312` `paramiko.transport.Transport` had a bug in its ``__repr__`` which + surfaces during errors encountered within its ``__init__``, causing + problematic tracebacks in such situations. Thanks to Simon Percivall for + catch & patch. +- :bug:`272` Fix a bug where ``known_hosts`` parsing hashed the input hostname + as well as the hostnames from the ``known_hosts`` file, on every comparison. + Thanks to ``@sigmunau`` for final patch and ``@ostacey`` for the original + report. +- :bug:`239` Add Windows-style CRLF support to SSH config file parsing. Props + to Christopher Swenson. +- :support:`229 backported` Fix a couple of incorrectly-copied docstrings' ``.. + versionadded::`` RST directives. Thanks to Aarni Koskela for the catch. +- :support:`169 backported` Minor refactor of + `paramiko.sftp_client.SFTPClient.put` thanks to Abhinav Upadhyay. +- :bug:`285` (also :issue:`352`) Update our Python 3 ``b()`` compatibility shim + to handle ``buffer`` objects correctly; this fixes a frequently reported + issue affecting many users, including users of the ``bzr`` software suite. + Thanks to ``@basictheprogram`` for the initial report, Jelmer Vernooij for + the fix and Andrew Starr-Bochicchio & Jeremy T. Bouse (among others) for + discussion & feedback. +- :support:`371` Add Travis support & docs update for Python 3.4. Thanks to + Olle Lundberg. +- :release:`1.14.0 <2014-05-07>` +- :release:`1.13.1 <2014-05-07>` +- :release:`1.12.4 <2014-05-07>` +- :release:`1.11.6 <2014-05-07>` +- :bug:`-` `paramiko.file.BufferedFile.read` incorrectly returned text strings + after the Python 3 migration, despite bytes being more appropriate for file + contents (which may be binary or of an unknown encoding.) This has been + addressed. + + .. note:: + `paramiko.file.BufferedFile.readline` continues to return strings, not + bytes, as "lines" only make sense for textual data. It assumes UTF-8 by + default. + + This should fix `this issue raised on the Obnam mailing list + `_. Thanks + to Antoine Brenner for the patch. +- :bug:`-` Added self.args for exception classes. Used for unpickling. Related + to (`Fabric #986 `_, `Fabric + #714 `_). Thanks to Alex + Plugaru. +- :bug:`-` Fix logging error in sftp_client for filenames containing the '%' + character. Thanks to Antoine Brenner. +- :bug:`308` Fix regression in dsskey.py that caused sporadic signature + verification failures. Thanks to Chris Rose. +- :support:`299` Use deterministic signatures for ECDSA keys for improved + security. Thanks to Alex Gaynor. +- :support:`297` Replace PyCrypto's ``Random`` with `os.urandom` for improved + speed and security. Thanks again to Alex. +- :support:`295` Swap out a bunch of PyCrypto hash functions with use of + `hashlib`. Thanks to Alex Gaynor. +- :support:`290` (also :issue:`292`) Add support for building universal + (Python 2+3 compatible) wheel files during the release process. Courtesy of + Alex Gaynor. +- :support:`284` Add Python language trove identifiers to ``setup.py``. Thanks + to Alex Gaynor for catch & patch. +- :bug:`235` Improve string type testing in a handful of spots (e.g. ``s/if + type(x) is str/if isinstance(x, basestring)/g``.) Thanks to ``@ksamuel`` for + the report. +- :release:`1.13.0 <2014-03-13>` +- :release:`1.12.3 <2014-03-13>` +- :release:`1.11.5 <2014-03-13>` +- :release:`1.10.7 <2014-03-13>` +- :feature:`16` **Python 3 support!** Our test suite passes under Python 3, and + it (& Fabric's test suite) continues to pass under Python 2. **Python 2.5 is + no longer supported with this change!** + + The merged code was built on many contributors' efforts, both code & + feedback. In no particular order, we thank Daniel Goertzen, Ivan Kolodyazhny, + Tomi Pieviläinen, Jason R. Coombs, Jan N. Schulze, ``@Lazik``, Dorian Pula, + Scott Maxwell, Tshepang Lekhonkhobe, Aaron Meurer, and Dave Halter. +- :support:`256 backported` Convert API documentation to Sphinx, yielding a new + API docs website to replace the old Epydoc one. Thanks to Olle Lundberg for + the initial conversion work. +- :bug:`-` Use constant-time hash comparison operations where possible, to + protect against `timing-based attacks + `_. Thanks to Alex Gaynor + for the patch. +- :release:`1.12.2 <2014-02-14>` +- :release:`1.11.4 <2014-02-14>` +- :release:`1.10.6 <2014-02-14>` +- :feature:`58` Allow client code to access the stored SSH server banner via + `Transport.get_banner `. Thanks to + ``@Jhoanor`` for the patch. +- :bug:`252` (`Fabric #1020 `_) + Enhanced the implementation of ``ProxyCommand`` to avoid a deadlock/hang + condition that frequently occurs at ``Transport`` shutdown time. Thanks to + Mateusz Kobos, Matthijs van der Vleuten and Guillaume Zitta for the original + reports and to Marius Gedminas for helping test nontrivial use cases. +- :bug:`268` Fix some missed renames of ``ProxyCommand`` related error classes. + Thanks to Marius Gedminas for catch & patch. +- :bug:`34` (PR :issue:`35`) Fix SFTP prefetching incompatibility with some + SFTP servers regarding request/response ordering. Thanks to Richard + Kettlewell. +- :bug:`193` (and its attentant PRs :issue:`230` & :issue:`253`) Fix SSH agent + problems present on Windows. Thanks to David Hobbs for initial report and to + Aarni Koskela & Olle Lundberg for the patches. +- :release:`1.12.1 <2014-01-08>` +- :release:`1.11.3 <2014-01-08>` +- :release:`1.10.5 <2014-01-08>` +- :bug:`225 (1.12+)` Note ecdsa requirement in README. Thanks to Amaury + Rodriguez for the catch. +- :bug:`176` Fix AttributeError bugs in known_hosts file (re)loading. Thanks + to Nathan Scowcroft for the patch & Martin Blumenstingl for the initial test + case. +- :release:`1.12.0 <2013-09-27>` +- :release:`1.11.2 <2013-09-27>` +- :release:`1.10.4 <2013-09-27>` +- :feature:`152` Add tentative support for ECDSA keys. **This adds the ecdsa + module as a new dependency of Paramiko.** The module is available at + `warner/python-ecdsa on Github `_ and + `ecdsa on PyPI `_. + + * Note that you might still run into problems with key negotiation -- + Paramiko picks the first key that the server offers, which might not be + what you have in your known_hosts file. + * Mega thanks to Ethan Glasser-Camp for the patch. + +- :feature:`136` Add server-side support for the SSH protocol's 'env' command. + Thanks to Benjamin Pollack for the patch. +- :bug:`156 (1.11+)` Fix potential deadlock condition when using Channel + objects as sockets (e.g. when using SSH gatewaying). Thanks to Steven Noonan + and Frank Arnold for catch & patch. +- :bug:`179` Fix a missing variable causing errors when an ssh_config file has + a non-default AddressFamily set. Thanks to Ed Marshall & Tomaz Muraus for + catch & patch. +- :bug:`200` Fix an exception-causing typo in ``demo_simple.py``. Thanks to Alex + Buchanan for catch & Dave Foster for patch. +- :bug:`199` Typo fix in the license header cross-project. Thanks to Armin + Ronacher for catch & patch. +- :release:`1.11.1 <2013-09-20>` +- :release:`1.10.3 <2013-09-20>` +- :bug:`162` Clean up HMAC module import to avoid deadlocks in certain uses of + SSHClient. Thanks to Gernot Hillier for the catch & suggested fix. +- :bug:`36` Fix the port-forwarding demo to avoid file descriptor errors. + Thanks to Jonathan Halcrow for catch & patch. +- :bug:`168` Update config handling to properly handle multiple 'localforward' + and 'remoteforward' keys. Thanks to Emre Yılmaz for the patch. +- :release:`1.11.0 <2013-07-26>` +- :release:`1.10.2 <2013-07-26>` +- :bug:`98 major` On Windows, when interacting with the PuTTY PAgeant, Paramiko + now creates the shared memory map with explicit Security Attributes of the + user, which is the same technique employed by the canonical PuTTY library to + avoid permissions issues when Paramiko is running under a different UAC + context than the PuTTY Ageant process. Thanks to Jason R. Coombs for the + patch. +- :support:`100` Remove use of PyWin32 in ``win_pageant`` module. Module was + already dependent on ctypes for constructing appropriate structures and had + ctypes implementations of all functionality. Thanks to Jason R. Coombs for + the patch. +- :bug:`87 major` Ensure updates to ``known_hosts`` files account for any + updates to said files after Paramiko initially read them. (Includes related + fix to guard against duplicate entries during subsequent ``known_hosts`` + loads.) Thanks to ``@sunweaver`` for the contribution. +- :bug:`153` (also :issue:`67`) Warn on parse failure when reading known_hosts + file. Thanks to ``@glasserc`` for patch. +- :bug:`146` Indentation fixes for readability. Thanks to Abhinav Upadhyay for + catch & patch. +- :release:`1.10.1 <2013-04-05>` +- :bug:`142` (`Fabric #811 `_) + SFTP put of empty file will still return the attributes of the put file. + Thanks to Jason R. Coombs for the patch. +- :bug:`154` (`Fabric #876 `_) + Forwarded SSH agent connections left stale local pipes lying around, which + could cause local (and sometimes remote or network) resource starvation when + running many agent-using remote commands. Thanks to Kevin Tegtmeier for catch + & patch. +- :release:`1.10.0 <2013-03-01>` +- :feature:`66` Batch SFTP writes to help speed up file transfers. Thanks to + Olle Lundberg for the patch. +- :bug:`133 major` Fix handling of window-change events to be on-spec and not + attempt to wait for a response from the remote sshd; this fixes problems with + less common targets such as some Cisco devices. Thanks to Phillip Heller for + catch & patch. +- :feature:`93` Overhaul SSH config parsing to be in line with ``man + ssh_config`` (& the behavior of ``ssh`` itself), including addition of parameter + expansion within config values. Thanks to Olle Lundberg for the patch. +- :feature:`110` Honor SSH config ``AddressFamily`` setting when looking up + local host's FQDN. Thanks to John Hensley for the patch. +- :feature:`128` Defer FQDN resolution until needed, when parsing SSH config + files. Thanks to Parantapa Bhattacharya for catch & patch. +- :bug:`102 major` Forego random padding for packets when running under + ``*-ctr`` ciphers. This corrects some slowdowns on platforms where random + byte generation is inefficient (e.g. Windows). Thanks to ``@warthog618`` for + catch & patch, and Michael van der Kolff for code/technique review. +- :feature:`127` Turn ``SFTPFile`` into a context manager. Thanks to Michael + Williamson for the patch. +- :feature:`116` Limit ``Message.get_bytes`` to an upper bound of 1MB to protect + against potential DoS vectors. Thanks to ``@mvschaik`` for catch & patch. +- :feature:`115` Add convenience ``get_pty`` kwarg to ``Client.exec_command`` so + users not manually controlling a channel object can still toggle PTY + creation. Thanks to Michael van der Kolff for the patch. +- :feature:`71` Add ``SFTPClient.putfo`` and ``.getfo`` methods to allow direct + uploading/downloading of file-like objects. Thanks to Eric Buehl for the + patch. +- :feature:`113` Add ``timeout`` parameter to ``SSHClient.exec_command`` for + easier setting of the command's internal channel object's timeout. Thanks to + Cernov Vladimir for the patch. +- :support:`94` Remove duplication of SSH port constant. Thanks to Olle + Lundberg for the catch. +- :feature:`80` Expose the internal "is closed" property of the file transfer + class ``BufferedFile`` as ``.closed``, better conforming to Python's file + interface. Thanks to ``@smunaut`` and James Hiscock for catch & patch. diff --git a/sites/www/conf.py b/sites/www/conf.py new file mode 100644 index 0000000..179f0b7 --- /dev/null +++ b/sites/www/conf.py @@ -0,0 +1,28 @@ +# Obtain shared config values +from pathlib import Path +import os +import sys + +updir = Path(__file__).parent.parent.resolve() +sys.path.append(str(updir)) +from shared_conf import * + +# Releases changelog extension +extensions.append("releases") +releases_release_uri = "https://github.com/paramiko/paramiko/tree/%s" +releases_issue_uri = "https://github.com/paramiko/paramiko/issues/%s" +releases_development_branch = "main" +# Don't show unreleased_X.x sections up top for 1.x or 2.x anymore +releases_supported_versions = [3] + +# Default is 'local' building, but reference the public docs site when building +# under RTD. +target = updir / "docs" / "_build" +if os.environ.get("READTHEDOCS") == "True": + target = "http://docs.paramiko.org/en/latest/" +intersphinx_mapping["docs"] = (str(target), None) + +# Sister-site links to API docs +html_theme_options["extra_nav_links"] = { + "API Docs": "http://docs.paramiko.org" +} diff --git a/sites/www/contact.rst b/sites/www/contact.rst new file mode 100644 index 0000000..202815f --- /dev/null +++ b/sites/www/contact.rst @@ -0,0 +1,12 @@ +======= +Contact +======= + +You can get in touch with the developer & user community in any of the +following ways: + +* Submit contributions on Github - see the :doc:`contributing` page. +* Follow ``@bitprophet`` on Twitter, though it's not a dedicated account and + mostly just retweets funny pictures. +* Subscribe to the ``paramiko`` category on the developer's blog: + http://bitprophet.org/categories/paramiko/ diff --git a/sites/www/contributing.rst b/sites/www/contributing.rst new file mode 100644 index 0000000..9cf0f34 --- /dev/null +++ b/sites/www/contributing.rst @@ -0,0 +1,25 @@ +============ +Contributing +============ + +How to get the code +=================== + +Our primary Git repository is on Github at `paramiko/paramiko`_; +please follow their instructions for cloning to your local system. (If you +intend to submit patches/pull requests, we recommend forking first, then +cloning your fork. Github has excellent documentation for all this.) + + +How to submit bug reports or new code +===================================== + +Please see `this project-agnostic contribution guide +`_ - we follow it explicitly. Again, our code +repository and bug tracker is `on Github`_. + +Our changelog is located in ``sites/www/changelog.rst``. + + +.. _paramiko/paramiko: +.. _on Github: https://github.com/paramiko/paramiko diff --git a/sites/www/faq.rst b/sites/www/faq.rst new file mode 100644 index 0000000..74b7501 --- /dev/null +++ b/sites/www/faq.rst @@ -0,0 +1,36 @@ +=================================== +Frequently Asked/Answered Questions +=================================== + +Which version should I use? I see multiple active releases. +=========================================================== + +Please see :ref:`the installation docs ` which have an explicit +section about this topic. + +Paramiko doesn't work with my Cisco, Windows or other non-Unix system! +====================================================================== + +In an ideal world, the developers would love to support every possible target +system. Unfortunately, volunteer development time and access to non-mainstream +platforms are limited, meaning that we can only fully support standard OpenSSH +implementations such as those found on the average Linux distribution (as well +as on Mac OS X and \*BSD.) + +Because of this, **we typically close bug reports for nonstandard SSH +implementations or host systems**. + +However, **closed does not imply locked** - affected users can still post +comments on such tickets - and **we will always consider actual patch +submissions for these issues**, provided they can get +1s from similarly +affected users and are proven to not break existing functionality. + +I'm having strange issues with my code hanging at shutdown! +=========================================================== + +Make sure you explicitly ``.close()`` your connection objects (usually +``SSHClient``) if you're having any sort of hang/freeze at shutdown time! + +Doing so isn't strictly necessary 100% of the time, but it is almost always the +right solution if you run into the various corner cases that cause race +conditions, etc. diff --git a/sites/www/index.rst b/sites/www/index.rst new file mode 100644 index 0000000..9c3bb3a --- /dev/null +++ b/sites/www/index.rst @@ -0,0 +1,13 @@ +.. include:: ../../README.rst + +.. toctree:: + :hidden: + + changelog + FAQs + installing + installing-1.x + contributing + contact + + diff --git a/sites/www/installing-1.x.rst b/sites/www/installing-1.x.rst new file mode 100644 index 0000000..7421a6c --- /dev/null +++ b/sites/www/installing-1.x.rst @@ -0,0 +1,121 @@ +================ +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. + +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 `_ 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 new file mode 100644 index 0000000..98c0655 --- /dev/null +++ b/sites/www/installing.rst @@ -0,0 +1,152 @@ +========== +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 +=============== + +The recommended way to get Paramiko is to **install the latest stable release** +via `pip `_:: + + $ pip install paramiko + +We currently support **Python 3.6+ only**. Users on older interpreter versions +are urged to upgrade. + +Paramiko has only a few **direct dependencies**: + +- The big one, with its own sub-dependencies, is Cryptography; see :ref:`its + specific note below ` for more details; +- `bcrypt `_ and `pynacl + `_ for Ed25519 key support. + +There are also a handful of **optional dependencies** you may install using +`setuptools 'extras' +`_: + +- If you want all optional dependencies at once, use ``paramiko[all]``. +- For ``Match exec`` config support and/or ``ProxyCommand`` feature support, + use ``paramiko[invoke]`` (which installs `Invoke + `_). +- For GSS-API / SSPI support, use ``paramiko[gssapi]``, though also see + :ref:`the below subsection on it ` for details. + + +.. _release-lines: + +Release lines +------------- + +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. 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. 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. + + +.. _cryptography: + +Cryptography +============ + +`Cryptography `__ provides the low-level (C-based) +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 + ``libffi``. Again, see `Cryptography's install docs`_; these requirements may + occasionally change. + + .. 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. + +* Similarly, Cryptography 3.4 and above require Rust language tooling to + install from source; once again see Cryptography's documentation for details + here, such as `their Rust install section`_ and `this FAQ entry`_. + +.. _installation instructions: +.. _Cryptography's install docs: https://cryptography.io/en/latest/installation.html +.. _their Rust install section: https://cryptography.io/en/latest/installation.html#rust +.. _this FAQ entry: https://cryptography.io/en/latest/faq.html#installing-cryptography-fails-with-error-can-not-find-rust-compiler + + +.. _gssapi: + +Optional dependencies for GSS-API / SSPI / Kerberos +=================================================== + +In order to use GSS-API/Kerberos & related functionality, additional +dependencies are required. It hopefully goes without saying but **all +platforms** need **a working installation of GSS-API itself**, e.g. Heimdal. + +.. note:: + If you use Microsoft SSPI for kerberos authentication and credential + 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 + +The ``gssapi`` "extra" install flavor +------------------------------------- + +If you're installing via ``pip`` (recommended), you should be able to get the +optional Python package requirements by changing your installation to refer to +``paramiko[gssapi]`` (from simply ``paramiko``), e.g.:: + + pip install "paramiko[gssapi]" + +(Or update your ``requirements.txt``, or etc.) + + +.. TODO: just axe this once legacy gssapi support is gone, no point reiterating + +Manual dependency installation +------------------------------ + +If you're not using ``pip`` or your ``pip`` is too old to support the "extras" +functionality, the optional dependencies are as follows: + +* All platforms need `pyasn1 `_ ``0.1.7`` or + later. +* **Unix** needs: `gssapi `__ ``1.4.1`` or better. + + * An alternative is the `python-gssapi + `_ library (``0.6.1`` or above), + though it is no longer maintained upstream, and Paramiko's support for + its API may eventually become deprecated. + +* **Windows** needs `pywin32 `_ ``2.1.8`` + or better. -- cgit v1.2.3