diff options
Diffstat (limited to 'sites')
| -rw-r--r-- | sites/docs/.readthedocs.yaml | 13 | ||||
| -rw-r--r-- | sites/docs/api/auth.rst | 8 | ||||
| -rw-r--r-- | sites/docs/index.rst | 1 | ||||
| -rw-r--r-- | sites/www/.readthedocs.yaml | 13 | ||||
| -rw-r--r-- | sites/www/changelog.rst | 138 | ||||
| -rw-r--r-- | sites/www/conf.py | 14 |
6 files changed, 182 insertions, 5 deletions
diff --git a/sites/docs/.readthedocs.yaml b/sites/docs/.readthedocs.yaml new file mode 100644 index 00000000..3212c930 --- /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/auth.rst b/sites/docs/api/auth.rst new file mode 100644 index 00000000..b6bce36c --- /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/index.rst b/sites/docs/index.rst index 87265d95..675fe596 100644 --- a/sites/docs/index.rst +++ b/sites/docs/index.rst @@ -47,6 +47,7 @@ Authentication & keys --------------------- .. toctree:: + api/auth api/agent api/hostkeys api/keys diff --git a/sites/www/.readthedocs.yaml b/sites/www/.readthedocs.yaml new file mode 100644 index 00000000..4f7d397e --- /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/changelog.rst b/sites/www/changelog.rst index 9d8ab3a1..2deb6998 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,144 @@ Changelog ========= +- :bug:`-` Tweak ``ext-info-(c|s)`` detection during KEXINIT protocol phase; + the original implementation made assumptions based on an OpenSSH + implementation detail. +- :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 <paramiko.client.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 <https://fabfile.org>`_. 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() <paramiko.agent.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 <paramiko.pkey.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 <paramiko.pkey.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 `<paramiko.hostkeys.HostKeyEntry.from_line>` 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 diff --git a/sites/www/conf.py b/sites/www/conf.py index 00944871..179f0b7f 100644 --- a/sites/www/conf.py +++ b/sites/www/conf.py @@ -1,22 +1,26 @@ # Obtain shared config values -import sys +from pathlib import Path import os -from os.path import abspath, join, dirname +import sys -sys.path.append(abspath(join(dirname(__file__), ".."))) +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 = join(dirname(__file__), "..", "docs", "_build") +target = updir / "docs" / "_build" if os.environ.get("READTHEDOCS") == "True": target = "http://docs.paramiko.org/en/latest/" -intersphinx_mapping["docs"] = (target, None) +intersphinx_mapping["docs"] = (str(target), None) # Sister-site links to API docs html_theme_options["extra_nav_links"] = { |