paramiko

[ Support ] #973 : Removed support for the DSA (aka DSS) key algorithm, as it has been badly outdated and insecure for a decade or more at this point, and was recently completely removed from OpenSSH as well.

If you were still using DSA out of sheer inertia: we strongly recommend upgrading to Ed25519 (or maybe ECDSA).

If you were still using DSA because of target hosts you do not control: please continue using Paramiko 3.x.

[ Support ] : Administrivia update:

dropped support for Python <3.9

migrated packaging metadata and practices to use pyproject.toml

removed the now-vestigial ed25519 packaging ‘extra’ (support for this hasn’t required additional dependencies in a number of releases now, just the core ones)

moved Invoke requirement to core dependencies, and removed paramiko[invoke] from extras

with those two changes, paramiko[all] becomes much less useful, and has itself been axed

removed the very old and wizened setup_helper.py which was only needed on ancient (for this century) versions of macOS.

removed paramiko.all , as it was redundant (guessing it dated back to some very old Python versions; anyone using import * these days - shame! - should still be fine as we never had any ‘private’ members in all and AFAICT that was the only reason ever to use it in the first place (as import * skips names like _private ).

[ Bug ] #2490 : Private key material is now explicitly ‘unpadded’ during decryption, removing a reliance on some lax OpenSSL behavior & making us compatible with future Cryptography releases. Patch courtesy of Alex Gaynor.

[ Feature ] #982 : (via #2444 , which was a rebase of #2157 ) Add support for AES-GCM encryption ciphers (128 and 256 bit variants). Thanks to Alex Gaynor for the report (& for cryptography review), Shen Cheng for the original PR, and Chris Mason for the updated PR; plus as usual to everyone who tested the patches and reported their results!

This functionality has been tested in client mode against OpenSSH 9.0, 9.2, and 9.6, as well as against a number of proprietary appliance SSH servers.

[ Bug ] #2353 : Fix a 64-bit-ism in the test suite so the tests don’t encounter a false negative on 32-bit systems. Reported by Stanislav Levin.

[ Bug ] #2420 : Modify a test-harness skiptest check to work with newer versions of Cryptography. Props to Paul Howarth for the patch.

[ Bug ] #2419 : (fixed in #2421 ) Massage our import of the TripleDES cipher to support Cryptography >=43; this should prevent CryptographyDeprecationWarning from appearing upon import. Thanks to Erick Alejo for the report and Bryan Banda for the patch.

[ 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 ] : Tweak ext-info-(c|s) detection during KEXINIT protocol phase; the original implementation made assumptions based on an OpenSSH implementation detail.

[ 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 ] #2353 : Fix a 64-bit-ism in the test suite so the tests don’t encounter a false negative on 32-bit systems. Reported by Stanislav Levin.

[ Bug ] #2420 : Modify a test-harness skiptest check to work with newer versions of Cryptography. Props to Paul Howarth for the patch.

[ Bug ] #2419 : (fixed in #2421 ) Massage our import of the TripleDES cipher to support Cryptography >=43; this should prevent CryptographyDeprecationWarning from appearing upon import. Thanks to Erick Alejo for the report and Bryan Banda for the patch.

[ 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

[ Feature ] #2058 : (solves #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 .

[ Feature ] #1907 : (solves #1992 ) Add support and tests for Match final … (frequently used in ProxyJump configurations to exclude the jump host) to our SSH config parser . Patch by @commonism .

[ Feature ] : 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.

[ Feature ] : PKey grew a new .algorithm_name property which displays the key algorithm; this is typically derived from the value of 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 ] : 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, PKey and friends grew an identifiers classmethod; this is inspired by the 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 ] : Enhanced 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 ] #387 : Users of 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 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 ] : Implement _fields() on AgentKey so that it may be compared (via == ) with other PKey instances.

[ Bug ] : AgentKey had a dangling Python 3 incompatible str method returning bytes. This method has been removed, allowing the superclass’ ( PKey ) method to run instead.

[ Bug ] #23 : 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 Transport subclass, 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.

[ Bug ] #2012 : (also #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 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).

[ Bug ] : 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.

[ Feature ] #2173 : Accept single tabs as field separators (in addition to single spaces) in <paramiko.hostkeys.HostKeyEntry.from_line> for parity with OpenSSH’s KnownHosts parser. Patched by Alex Chavkin.

[ Feature ] #2013 : (solving #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.

[ Support ] #2178 : 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.

[ Bug ] : 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.

[ Bug ] #2165 : 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.

[ Bug ] #2110 : 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.

[ 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.

[ 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 ] : 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 ] : 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.

[ Support ] : The behavior of private key classes’ (ie anything inheriting from 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 ] #732 : (also re: #630 ) 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 ] : 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.

[ Feature ] #2125 : (also re: #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.

[ Bug ] : bug: 1637 (via #1599 ) Raise 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.

[ Bug ] #1822 : (via, and relating to, far too many other issues to mention here) Update 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 .

[ Feature ] #1951 : Add SSH config token expansion (eg %h , %p ) when parsing ProxyJump directives. Patch courtesy of Bruno Inec.

[ Support ] #2004 : (via #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.

[ Support ] #1838 : (via #1870 / #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.

[ Support ] #2038 : (via #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 ] : bug: 1637 (via #1599 ) Raise 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.

[ Bug ] #1822 : (via, and relating to, far too many other issues to mention here) Update 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 ] #2008 : (via #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.

[ 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.

[ 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 ] #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.

[ Bug ] #1964 : (via #2024 as also reported in #2023 ) 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 ] #1838 : (via #1870 / #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.

[ Bug ] #2002 : (via #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.

[ Bug ] #1963 : (via #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 ] #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 .

[ Bug ] : ( CVE-2022-24302 ) Creation of new private key files using 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.

[ Feature ] #1509 : (via #1868 , #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.

[ Feature ] #1976 : Add support for the %C token when parsing SSH config files. Foundational PR submitted by @jbrand42 .

[ Bug ] #892 : Significantly speed up low-level read/write actions on 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.

[ Bug ] #2008 : (via #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.

[ 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.

[ 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 ] #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.

[ Bug ] #1964 : (via #2024 as also reported in #2023 ) 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 ] #1838 : (via #1870 / #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.

[ 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 .

[ Bug ] #2002 : (via #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.

[ Bug ] #1963 : (via #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 ] : 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.

[ 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 ] #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.

[ Feature ] #1643 : (also #1925 , #1644 , #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 RSAKey ).

A new SSHException subclass was added, 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.

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.

[ Bug ] : (also #908 ) Update 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.

[ Bug ] #1257 : (also #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 SSHException instances instead of bubbling up. Thanks to Ignat Semenov for the report and @tylergarcianet for an early patch.

[ Bug ] #1024 : Deleting items from HostKeys would incorrectly raise KeyError even for valid keys, due to a logic bug. This has been fixed. Report & patch credit: Jia Zhang.

[ Bug ] #985 : (via #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.

[ 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.

[ Bug ] #1462 : (via #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.

[ Support ] #1722 : Remove leading whitespace from OpenSSH RSA test suite static key fixture, to conform better to spec. Credit: Alex Gaynor.

[ Support ] #1727 : 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 ] : Update our CI to catch issues with sdist generation, installation and testing.

[ 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 ] #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.

[ Bug ] : Fix incorrect string formatting causing unhelpful error message annotation when using Kerberos/GSSAPI. (Thanks, newer version of flake8!)

[ Support ] #1722 : Remove leading whitespace from OpenSSH RSA test suite static key fixture, to conform better to spec. Credit: Alex Gaynor.

[ Support ] #1727 : 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 ] : Update our CI to catch issues with sdist generation, installation and testing.

[ Bug ] #1565 : (via #1566 ) Fix a bug in support for ECDSA keys under the newly supported OpenSSH key format. Thanks to Pierce Lopez for the patch.

[ 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.

[ Feature ] : Add new convenience classmethod constructors to SSHConfig : from_text , from_file , and from_path . No more annoying two-step process!

[ 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.

[ 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 optional install dependency , Invoke , for managing Match exec subprocesses.

[ Feature ] : A couple of outright SSHConfig parse errors were previously represented as vanilla Exception instances; as part of recent feature work a more specific exception class, ConfigParseError , has been created. It is now also used in those older spots, which is naturally backwards compatible.

[ Feature ] #602 : (via #1343 , #1313 , #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 ] : 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.

[ Bug ] : 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 ] : ssh_config 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 .

[ Support ] : Explicitly document which ssh_config features we currently support . Previously users just had to guess, which is simply no good.

[ Support ] : Additional installation extras_require “flavors” ( ed25519 , invoke , and all ) have been added to our packaging metadata; see the install docs for details.

[ Feature ] #1463 : Add a new keyword argument to SSHClient.connect and 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.

[ Bug ] #322 : SSHClient.exec_command previously returned a naive 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, ChannelStdinFile , has been created which closes remote stdin when it itself is closed. exec_command has been updated to use that class for its stdin return value.

Thanks to Brandon Rhodes for the report & steps to reproduce.

[ Support ] #1311 : (for #584 , replacing #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.

[ Support ] #1440 : (with initial fixes via #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.

[ Bug ] #1306 : (via #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.

[ Feature ] #1212 : Updated SSHConfig.lookup so it returns a new, type-casting-friendly dict subclass ( 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.

[ Feature ] #532 : (via #1384 and #1258 ) Add support for Curve25519 key exchange (aka curve25519-sha256@libssh.org ). Thanks to Alex Gaynor and Dan Fuhry for supplying patches.

[ Feature ] #1233 : (also #1229 , #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.

[ 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.

[ Support ] #1262 : Add *.pub files to the MANIFEST so distributed source packages contain some necessary test assets. Credit: Alexander Kapshuna.

[ Support ] #1378 : 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.

[ Support ] #1379 : (also #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.

[ Bug ] #1306 : (via #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 ] #1378 : 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.

[ 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.

[ 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).

[ Support ] #1262 : Add *.pub files to the MANIFEST so distributed source packages contain some necessary test assets. Credit: Alexander Kapshuna.

[ 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.

[ 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 ] #1175 : 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.

[ 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 ] #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.

[ Support ] : Include LICENSE file in wheel archives.

[ 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 ] : 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 ] #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.

[ 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).

[ Support ] #1262 : Add *.pub files to the MANIFEST so distributed source packages contain some necessary test assets. Credit: Alexander Kapshuna.

[ Bug ] #1108 : 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.

[ 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.

[ 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 ] #1175 : 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.

[ Support ] : Include LICENSE file in wheel archives.

[ 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.

[ Feature ] #1042 : (also partially #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 ( #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.

[ 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.

[ Feature ] #1026 : Update Ed25519Key so its constructor offers the same file_obj parameter as its sibling key classes. Credit: Michal Kuffa.

[ 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 ] #60 : (via #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 ] #1012 : (via #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.

[ 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 ] : 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.

[ Support ] : Ed25519 keys never got proper API documentation support; this has been fixed.

[ 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.

[ 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.

[ 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).

[ Support ] #1262 : Add *.pub files to the MANIFEST so distributed source packages contain some necessary test assets. Credit: Alexander Kapshuna.

[ 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.

[ Bug ] #1108 : 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.

[ 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.

[ 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 ] #1175 : 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.

[ Support ] : Include LICENSE file in wheel archives.

[ Bug ] #945 : (backport of #910 and re: #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.

[ Bug ] #1055 : (also #1056 , #1057 , #1058 , #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 ] #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 ] #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 ] #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 Transport would cause a MIC failure and terminate the connection. Thanks to Sebastian Deiß and Anselm Kruis for the patch.

[ 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.

[ 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.

[ Feature ] #325 : (via #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.

[ 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.

[ 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 ] #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 .

[ Feature ] #65 : (via #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.

[ Support ] #866 : (also #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.

[ Support ] #974 : 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!

[ Support ] : 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.

[ Support ] #956 : 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.

[ Support ] #921 : Tighten up the hash implementation for various key classes; less code is good code. Thanks to Francisco Couzo for the patch.

[ Support ] #906 : Clean up a handful of outdated imports and related tweaks. Thanks to Pierce Lopez.

[ 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.

[ 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).

[ Support ] #1262 : Add *.pub files to the MANIFEST so distributed source packages contain some necessary test assets. Credit: Alexander Kapshuna.

[ 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.

[ Bug ] #1108 : 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.

[ 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.

[ 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 ] #1175 : 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.

[ Support ] : Include LICENSE file in wheel archives.

[ 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.

[ 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 ] #945 : (backport of #910 and re: #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.

[ Bug ] #1055 : (also #1056 , #1057 , #1058 , #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 ] #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 ] #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 ] #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 Transport would cause a MIC failure and terminate the connection. Thanks to Sebastian Deiß and Anselm Kruis for the patch.

[ Bug ] #683 : Make util.log_to_file append instead of replace. Thanks to @vlcinsky for the report.

[ Bug ] #949 : 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 ] #794 : (via #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.

[ Bug ] #900 : (via #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 ] #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.

[ 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 ] #741 : (also #809 , #772 ; all via #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.

[ Bug ] #971 : 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 ] #984 : Enhance default cipher preference order such that aes(192|256)-cbc are preferred over blowfish-cbc . Thanks to Alex Gaynor.

[ 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 ] #974 : 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!

[ Support ] : 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.

[ Support ] #956 : 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 ] #895 : Fix a bug in server-mode concerning multiple interactive auth steps (which were incorrectly responded to). Thanks to Dennis Kaarsemaker for catch & patch.

[ Bug ] #44 : (via #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 ] #862 : (via #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 ] #853 : Tweak how RSAKey.str behaves so it doesn’t cause TypeError under Python 3. Thanks to Francisco Couzo for the report.

[ Support ] #866 : (also #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.

[ Bug ] #859 : (via #860 ) A tweak to the original patch implementing #398 was not fully applied, causing calls to 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 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 #860 ) A tweak to the original patch implementing #398 was not fully applied, causing calls to invoke_shell to fail with AttributeError . This has been fixed. Patch credit: Kirk Byers.

[ Feature ] #398 : 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.

[ Feature ] #780 : (also #779 , and may help users affected by #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 .

[ Support ] #854 : Fix incorrect docstring/param-list for Transport.auth_gssapi_keyex so it matches the real signature. Caught by @Score_Under .

[ Support ] #792 : Minor updates to the README and demos; thanks to Alan Yee.

[ Support ] #801 : Skip a Unix-only test when on Windows; thanks to Gabi Davar.

[ 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.

[ 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).

[ Support ] #1262 : Add *.pub files to the MANIFEST so distributed source packages contain some necessary test assets. Credit: Alexander Kapshuna.

[ 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.

[ Bug ] #1108 : 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.

[ 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.

[ 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 ] #1175 : 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.

[ Support ] : Include LICENSE file in wheel archives.

[ 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.

[ 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 ] #945 : (backport of #910 and re: #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.

[ Bug ] #1055 : (also #1056 , #1057 , #1058 , #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 ] #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 ] #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 ] #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 Transport would cause a MIC failure and terminate the connection. Thanks to Sebastian Deiß and Anselm Kruis for the patch.

[ Bug ] #683 : Make util.log_to_file append instead of replace. Thanks to @vlcinsky for the report.

[ Bug ] #949 : 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 ] #794 : (via #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.

[ Bug ] #900 : (via #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 ] #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.

[ 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 ] #741 : (also #809 , #772 ; all via #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.

[ Bug ] #971 : 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 ] #984 : Enhance default cipher preference order such that aes(192|256)-cbc are preferred over blowfish-cbc . Thanks to Alex Gaynor.

[ 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 ] #974 : 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!

[ Support ] : 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.

[ Support ] #956 : 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.