Adding upstream version 3.4.0.upstream/3.4.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

22 files changed, 380 insertions, 0 deletions

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
+<ssh_config>`_, 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 <ssh_config>`_ (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 <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 <TOKENS>`
+- ``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 <paramiko-itself>` (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
+  <TOKENS>`.
+- ``ProxyCommand``: see our `.ProxyCommand` class for an easy
+  way to honor this keyword from a config you've parsed.
+
+    - Honors :ref:`token expansion <TOKENS>`.
+    - 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>`.
+
+.. _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 <http://paramiko.org>`_.
+
+
+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