.. module:: asyncssh

.. _API:

API Documentation
*****************

Overview
========

The AsyncSSH API is modeled after the new Python ``asyncio`` framework, with
a :func:`create_connection` coroutine to create an SSH client and a
:func:`create_server` coroutine to create an SSH server. Like the
``asyncio`` framework, these calls take a parameter of a factory which
creates protocol objects to manage the connections once they are open.
For AsyncSSH, :func:`create_connection` should be passed a ``client_factory``
which returns objects derived from :class:`SSHClient` and :func:`create_server`
should be passed a ``server_factory`` which returns objects derived from
:class:`SSHServer`. In addition, each connection will have an associated
:class:`SSHClientConnection` or :class:`SSHServerConnection` object passed
to the protocol objects which can be used to perform actions on the connection.

For client connections, authentication can be performed by passing in a
username and password or SSH keys as arguments to :func:`create_connection`
or by implementing handler methods on the :class:`SSHClient` object which
return credentials when the server requests them. If no credentials are
provided, AsyncSSH automatically attempts to send the username of the
local user and the keys found in their :file:`.ssh` subdirectory. A list of
expected server host keys can also be specified, with AsyncSSH defaulting
to looking for matching lines in the user's :file:`.ssh/known_hosts` file.

For server connections, handlers can be implemented on the :class:`SSHServer`
object to return which authentication methods are supported and to validate
credentials provided by clients.

Once an SSH client connection is established and authentication is successful,
multiple simultaneous channels can be opened on it.  This is accomplished
calling methods such as :meth:`create_session()
<SSHClientConnection.create_session>`, :meth:`create_connection()
<SSHClientConnection.create_connection>`, and :meth:`create_unix_connection()
<SSHClientConnection.create_unix_connection>` on the
:class:`SSHClientConnection` object. The client can also set up listeners on
remote TCP ports and UNIX domain sockets by calling :meth:`create_server()
<SSHClientConnection.create_server>` and :meth:`create_unix_server()
<SSHClientConnection.create_unix_server>`. All of these methods take
``session_factory`` arguments that return :class:`SSHClientSession`,
:class:`SSHTCPSession`, or :class:`SSHUNIXSession` objects used to manage
the channels once they are open. Alternately, channels can be opened using
:meth:`open_session() <SSHClientConnection.open_session>`,
:meth:`open_connection() <SSHClientConnection.open_connection>`, or
:meth:`open_unix_connection() <SSHClientConnection.open_unix_connection>`,
which return :class:`SSHReader` and :class:`SSHWriter` objects that can be
used to perform I/O on the channel. The methods :meth:`start_server()
<SSHClientConnection.start_server>` and :meth:`start_unix_server()
<SSHClientConnection.start_unix_server>` can be used to set up listeners on
remote TCP ports or UNIX domain sockets and get back these :class:`SSHReader`
and :class:`SSHWriter` objects in a callback when new connections are opened.

SSH client sessions can also be opened by calling :meth:`create_process()
<SSHClientConnection.create_process>`. This returns a :class:`SSHClientProcess`
object which has members ``stdin``, ``stdout``, and ``stderr`` which are
:class:`SSHReader` and :class:`SSHWriter` objects. This API also makes
it very easy to redirect input and output from the remote process to local
files, pipes, sockets, or other :class:`SSHReader` and :class:`SSHWriter`
objects. In cases where you just want to run a remote process to completion
and get back an object containing captured output and exit status, the
:meth:`run() <SSHClientConnection.run>` method can be used. It returns an
:class:`SSHCompletedProcess` with the results of the run, or can be set up
to raise :class:`ProcessError` if the process exits with a non-zero exit
status.

The client can also set up TCP port forwarding by calling
:meth:`forward_local_port() <SSHClientConnection.forward_local_port>` or
:meth:`forward_remote_port() <SSHClientConnection.forward_remote_port>` and
UNIX domain socket forwarding by calling :meth:`forward_local_path()
<SSHClientConnection.forward_local_path>` or :meth:`forward_remote_path()
<SSHClientConnection.forward_remote_path>`. In these cases, data transfer on
the channels is managed automatically by AsyncSSH whenever new connections
are opened, so custom session objects are not required.

When an SSH server receives a new connection and authentication is successful,
handlers such as :meth:`session_requested() <SSHServer.session_requested>`,
:meth:`connection_requested() <SSHServer.connection_requested>`,
:meth:`unix_connection_requested() <SSHServer.unix_connection_requested>`,
:meth:`server_requested() <SSHServer.server_requested>`, and
:meth:`unix_server_requested() <SSHServer.unix_server_requested>` on the
associated :class:`SSHServer` object will be called when clients attempt to
open channels or set up listeners. These methods return coroutines which can
set up the requested sessions or connections, returning
:class:`SSHServerSession` or :class:`SSHTCPSession` objects or handler
functions that accept :class:`SSHReader` and :class:`SSHWriter` objects
as arguments which manage the channels once they are open.

To better support interactive server applications, AsyncSSH defaults to
providing echoing of input and basic line editing capabilities when an
inbound SSH session requests a pseudo-terminal. This behavior can be
disabled by setting the ``line_editor`` argument to ``False`` when
starting up an SSH server. When this feature is enabled, server sessions
can enable or disable line mode using the :meth:`set_line_mode()
<SSHLineEditorChannel.set_line_mode>` method of :class:`SSHLineEditorChannel`.
They can also enable or disable input echoing using the :meth:`set_echo()
<SSHLineEditorChannel.set_echo>` method.

Each session object also has an associated :class:`SSHClientChannel`,
:class:`SSHServerChannel`, or :class:`SSHTCPChannel` object passed to it
which can be used to perform actions on the channel. These channel objects
provide a superset of the functionality found in ``asyncio`` transport
objects.

In addition to the above functions and classes, helper functions for importing
public and private keys can be found below under :ref:`PublicKeySupport`,
exceptions can be found under :ref:`Exceptions`, supported algorithms can
be found under :ref:`SupportedAlgorithms`, and some useful constants can be
found under :ref:`Constants`.

Main Functions
==============

create_connection
-----------------

.. autofunction:: create_connection

create_server
-------------

.. autofunction:: create_server

connect
-------

.. autofunction:: connect

listen
------

.. autofunction:: listen

scp
---

.. autofunction:: scp

Main Classes
============

SSHClient
---------

.. autoclass:: SSHClient

   ================================== =
   General connection handlers
   ================================== =
   .. automethod:: connection_made
   .. automethod:: connection_lost
   .. automethod:: debug_msg_received
   ================================== =

   ==================================== =
   General authentication handlers
   ==================================== =
   .. automethod:: auth_banner_received
   .. automethod:: auth_completed
   ==================================== =

   ========================================= =
   Public key authentication handlers
   ========================================= =
   .. automethod:: public_key_auth_requested
   ========================================= =

   ========================================= =
   Password authentication handlers
   ========================================= =
   .. automethod:: password_auth_requested
   .. automethod:: password_change_requested
   .. automethod:: password_changed
   .. automethod:: password_change_failed
   ========================================= =

   ============================================ =
   Keyboard-interactive authentication handlers
   ============================================ =
   .. automethod:: kbdint_auth_requested
   .. automethod:: kbdint_challenge_received
   ============================================ =

SSHServer
---------

.. autoclass:: SSHServer

   ================================== =
   General connection handlers
   ================================== =
   .. automethod:: connection_made
   .. automethod:: connection_lost
   .. automethod:: debug_msg_received
   ================================== =

   =============================== =
   General authentication handlers
   =============================== =
   .. automethod:: begin_auth
   =============================== =

   ====================================== =
   GSSAPI authentication handlers
   ====================================== =
   .. automethod:: validate_gss_principal
   ====================================== =

   ========================================= =
   Public key authentication handlers
   ========================================= =
   .. automethod:: public_key_auth_supported
   .. automethod:: validate_public_key
   .. automethod:: validate_ca_key
   ========================================= =

   ======================================= =
   Password authentication handlers
   ======================================= =
   .. automethod:: password_auth_supported
   .. automethod:: validate_password
   .. automethod:: change_password
   ======================================= =

   ============================================ =
   Keyboard-interactive authentication handlers
   ============================================ =
   .. automethod:: kbdint_auth_supported
   .. automethod:: get_kbdint_challenge
   .. automethod:: validate_kbdint_response
   ============================================ =

   ========================================= =
   Channel session open handlers
   ========================================= =
   .. automethod:: session_requested
   .. automethod:: connection_requested
   .. automethod:: unix_connection_requested
   .. automethod:: server_requested
   .. automethod:: unix_server_requested
   ========================================= =

Connection Classes
==================

SSHClientConnection
-------------------

.. autoclass:: SSHClientConnection()

   ============================== =
   General connection methods
   ============================== =
   .. automethod:: get_extra_info
   .. automethod:: send_debug
   ============================== =

   ================================================================================================================================= =
   Client session open methods
   ================================================================================================================================= =
   .. automethod:: create_session
   .. automethod:: open_session
   .. automethod:: create_process(*args, bufsize=io.DEFAULT_BUFFER_SIZE, input=None, stdin=PIPE, stdout=PIPE, stderr=PIPE, **kwargs)
   .. automethod:: run(*args, check=False, **kwargs)
   .. automethod:: start_sftp_client
   .. automethod:: create_ssh_connection
   .. automethod:: connect_ssh
   ================================================================================================================================= =

   ====================================== =
   Client connection open methods
   ====================================== =
   .. automethod:: create_connection
   .. automethod:: open_connection
   .. automethod:: create_server
   .. automethod:: start_server
   .. automethod:: create_unix_connection
   .. automethod:: open_unix_connection
   .. automethod:: create_unix_server
   .. automethod:: start_unix_server
   ====================================== =

   =================================== =
   Client forwarding methods
   =================================== =
   .. automethod:: forward_connection
   .. automethod:: forward_local_port
   .. automethod:: forward_local_path
   .. automethod:: forward_remote_port
   .. automethod:: forward_remote_path
   =================================== =

   =========================== =
   Connection close methods
   =========================== =
   .. automethod:: abort
   .. automethod:: close
   .. automethod:: disconnect
   .. automethod:: wait_closed
   =========================== =

SSHServerConnection
-------------------

.. autoclass:: SSHServerConnection()

   ============================== =
   General connection methods
   ============================== =
   .. automethod:: get_extra_info
   .. automethod:: send_debug
   ============================== =

   ============================================ =
   Server authentication methods
   ============================================ =
   .. automethod:: send_auth_banner
   .. automethod:: set_authorized_keys
   .. automethod:: get_key_option
   .. automethod:: check_key_permission
   .. automethod:: get_certificate_option
   .. automethod:: check_certificate_permission
   ============================================ =

   ====================================== =
   Server connection open methods
   ====================================== =
   .. automethod:: create_connection
   .. automethod:: open_connection
   .. automethod:: create_unix_connection
   .. automethod:: open_unix_connection
   ====================================== =

   ======================================= =
   Server forwarding methods
   ======================================= =
   .. automethod:: forward_connection
   .. automethod:: forward_unix_connection
   ======================================= =

   ===================================== =
   Server channel creation methods
   ===================================== =
   .. automethod:: create_server_channel
   .. automethod:: create_tcp_channel
   .. automethod:: create_unix_channel
   ===================================== =

   =========================== =
   Connection close methods
   =========================== =
   .. automethod:: abort
   .. automethod:: close
   .. automethod:: disconnect
   .. automethod:: wait_closed
   =========================== =

Process Classes
===============

SSHClientProcess
----------------

.. autoclass:: SSHClientProcess

   ============================== =
   Client process attributes
   ============================== =
   .. autoattribute:: channel
   .. autoattribute:: env
   .. autoattribute:: command
   .. autoattribute:: subsystem
   .. autoattribute:: stdin
   .. autoattribute:: stdout
   .. autoattribute:: stderr
   .. autoattribute:: exit_status
   .. autoattribute:: exit_signal
   ============================== =

   ==================================== =
   Other client process methods
   ==================================== =
   .. automethod:: redirect
   .. automethod:: communicate
   .. automethod:: wait
   .. automethod:: change_terminal_size
   .. automethod:: send_break
   .. automethod:: send_signal
   ==================================== =

   ============================ =
   Client process close methods
   ============================ =
   .. automethod:: terminate
   .. automethod:: kill
   .. automethod:: close
   .. automethod:: wait_closed
   ============================ =

SSHServerProcess
----------------

.. autoclass:: SSHServerProcess

   ============================== =
   Server process attributes
   ============================== =
   .. autoattribute:: channel
   .. autoattribute:: env
   .. autoattribute:: command
   .. autoattribute:: subsystem
   .. autoattribute:: stdin
   .. autoattribute:: stdout
   .. autoattribute:: stderr
   ============================== =

   ================================= =
   Other server process methods
   ================================= =
   .. automethod:: get_terminal_type
   .. automethod:: get_terminal_size
   .. automethod:: get_terminal_mode
   .. automethod:: redirect
   ================================= =

   ================================ =
   Server process close methods
   ================================ =
   .. automethod:: exit
   .. automethod:: exit_with_signal
   .. automethod:: close
   .. automethod:: wait_closed
   ================================ =

SSHCompletedProcess
-------------------

.. autoclass:: SSHCompletedProcess()

Session Classes
===============

SSHClientSession
----------------

.. autoclass:: SSHClientSession

   =============================== =
   General session handlers
   =============================== =
   .. automethod:: connection_made
   .. automethod:: connection_lost
   .. automethod:: session_started
   =============================== =

   ============================= =
   General session read handlers
   ============================= =
   .. automethod:: data_received
   .. automethod:: eof_received
   ============================= =

   ============================== =
   General session write handlers
   ============================== =
   .. automethod:: pause_writing
   .. automethod:: resume_writing
   ============================== =

   ==================================== =
   Other client session handlers
   ==================================== =
   .. automethod:: xon_xoff_requested
   .. automethod:: exit_status_received
   .. automethod:: exit_signal_received
   ==================================== =

SSHServerSession
----------------

.. autoclass:: SSHServerSession

   =============================== =
   General session handlers
   =============================== =
   .. automethod:: connection_made
   .. automethod:: connection_lost
   .. automethod:: session_started
   =============================== =

   =================================== =
   Server session open handlers
   =================================== =
   .. automethod:: pty_requested
   .. automethod:: shell_requested
   .. automethod:: exec_requested
   .. automethod:: subsystem_requested
   =================================== =

   ============================= =
   General session read handlers
   ============================= =
   .. automethod:: data_received
   .. automethod:: eof_received
   ============================= =

   ============================== =
   General session write handlers
   ============================== =
   .. automethod:: pause_writing
   .. automethod:: resume_writing
   ============================== =

   ===================================== =
   Other server session handlers
   ===================================== =
   .. automethod:: break_received
   .. automethod:: signal_received
   .. automethod:: terminal_size_changed
   ===================================== =

SSHTCPSession
-------------

.. autoclass:: SSHTCPSession

   =============================== =
   General session handlers
   =============================== =
   .. automethod:: connection_made
   .. automethod:: connection_lost
   .. automethod:: session_started
   =============================== =

   ============================= =
   General session read handlers
   ============================= =
   .. automethod:: data_received
   .. automethod:: eof_received
   ============================= =

   ============================== =
   General session write handlers
   ============================== =
   .. automethod:: pause_writing
   .. automethod:: resume_writing
   ============================== =

SSHUNIXSession
--------------

.. autoclass:: SSHUNIXSession

   =============================== =
   General session handlers
   =============================== =
   .. automethod:: connection_made
   .. automethod:: connection_lost
   .. automethod:: session_started
   =============================== =

   ============================= =
   General session read handlers
   ============================= =
   .. automethod:: data_received
   .. automethod:: eof_received
   ============================= =

   ============================== =
   General session write handlers
   ============================== =
   .. automethod:: pause_writing
   .. automethod:: resume_writing
   ============================== =

Channel Classes
===============

SSHClientChannel
----------------

.. autoclass:: SSHClientChannel()

   =============================== =
   General channel info methods
   =============================== =
   .. automethod:: get_extra_info
   .. automethod:: get_environment
   .. automethod:: get_command
   .. automethod:: get_subsystem
   =============================== =

   ============================== =
   Client channel read methods
   ============================== =
   .. automethod:: pause_reading
   .. automethod:: resume_reading
   ============================== =

   ======================================= =
   Client channel write methods
   ======================================= =
   .. automethod:: can_write_eof
   .. automethod:: get_write_buffer_size
   .. automethod:: set_write_buffer_limits
   .. automethod:: write
   .. automethod:: writelines
   .. automethod:: write_eof
   ======================================= =

   ===================================== =
   Other client channel methods
   ===================================== =
   .. automethod:: get_exit_status
   .. automethod:: get_exit_signal
   .. automethod:: change_terminal_size
   .. automethod:: send_break
   .. automethod:: send_signal
   .. automethod:: kill
   .. automethod:: terminate
   ===================================== =

   ============================= =
   General channel close methods
   ============================= =
   .. automethod:: abort
   .. automethod:: close
   .. automethod:: wait_closed
   ============================= =

SSHServerChannel
----------------

.. autoclass:: SSHServerChannel()

   =============================== =
   General channel info methods
   =============================== =
   .. automethod:: get_extra_info
   .. automethod:: get_environment
   .. automethod:: get_command
   .. automethod:: get_subsystem
   =============================== =

   ================================= =
   Server channel info methods
   ================================= =
   .. automethod:: get_terminal_type
   .. automethod:: get_terminal_size
   .. automethod:: get_terminal_mode
   .. automethod:: get_x11_display
   .. automethod:: get_agent_path
   ================================= =

   ============================== =
   Server channel read methods
   ============================== =
   .. automethod:: pause_reading
   .. automethod:: resume_reading
   ============================== =

   ======================================= =
   Server channel write methods
   ======================================= =
   .. automethod:: can_write_eof
   .. automethod:: get_write_buffer_size
   .. automethod:: set_write_buffer_limits
   .. automethod:: write
   .. automethod:: writelines
   .. automethod:: write_stderr
   .. automethod:: writelines_stderr
   .. automethod:: write_eof
   ======================================= =

   ================================= =
   Other server channel methods
   ================================= =
   .. automethod:: set_xon_xoff
   .. automethod:: exit
   .. automethod:: exit_with_signal
   ================================= =

   ============================= =
   General channel close methods
   ============================= =
   .. automethod:: abort
   .. automethod:: close
   .. automethod:: wait_closed
   ============================= =

SSHLineEditorChannel
--------------------

.. autoclass:: SSHLineEditorChannel()

   ============================= =
   Line editor methods
   ============================= =
   .. automethod:: set_line_mode
   .. automethod:: set_echo
   ============================= =

SSHTCPChannel
-------------

.. autoclass:: SSHTCPChannel()

   ============================== =
   General channel info methods
   ============================== =
   .. automethod:: get_extra_info
   ============================== =

   ============================== =
   General channel read methods
   ============================== =
   .. automethod:: pause_reading
   .. automethod:: resume_reading
   ============================== =

   ======================================= =
   General channel write methods
   ======================================= =
   .. automethod:: can_write_eof
   .. automethod:: get_write_buffer_size
   .. automethod:: set_write_buffer_limits
   .. automethod:: write
   .. automethod:: writelines
   .. automethod:: write_eof
   ======================================= =

   ============================= =
   General channel close methods
   ============================= =
   .. automethod:: abort
   .. automethod:: close
   .. automethod:: wait_closed
   ============================= =

SSHUNIXChannel
--------------

.. autoclass:: SSHUNIXChannel()

   ============================== =
   General channel info methods
   ============================== =
   .. automethod:: get_extra_info
   ============================== =

   ============================== =
   General channel read methods
   ============================== =
   .. automethod:: pause_reading
   .. automethod:: resume_reading
   ============================== =

   ======================================= =
   General channel write methods
   ======================================= =
   .. automethod:: can_write_eof
   .. automethod:: get_write_buffer_size
   .. automethod:: set_write_buffer_limits
   .. automethod:: write
   .. automethod:: writelines
   .. automethod:: write_eof
   ======================================= =

   ============================= =
   General channel close methods
   ============================= =
   .. automethod:: abort
   .. automethod:: close
   .. automethod:: wait_closed
   ============================= =

Listener Classes
================

SSHListener
-----------

.. autoclass:: SSHListener()

   =========================== =
   .. automethod:: get_port
   .. automethod:: close
   .. automethod:: wait_closed
   =========================== =

Stream Classes
==============

SSHReader
---------

.. autoclass:: SSHReader()

   ============================== =
   .. autoattribute:: channel
   .. automethod:: get_extra_info
   .. automethod:: at_eof
   .. automethod:: read
   .. automethod:: readline
   .. automethod:: readuntil
   .. automethod:: readexactly
   ============================== =

SSHWriter
---------

.. autoclass:: SSHWriter()

   ============================== =
   .. autoattribute:: channel
   .. automethod:: get_extra_info
   .. automethod:: can_write_eof
   .. automethod:: close
   .. automethod:: drain
   .. automethod:: write
   .. automethod:: writelines
   .. automethod:: write_eof
   ============================== =

SFTP Support
============

SFTPClient
----------

.. autoclass:: SFTPClient()

   ===================== =
   File transfer methods
   ===================== =
   .. automethod:: get
   .. automethod:: put
   .. automethod:: copy
   .. automethod:: mget
   .. automethod:: mput
   .. automethod:: mcopy
   ===================== =

   ========================================================================================== =
   File access methods
   ========================================================================================== =
   .. automethod:: open(path, mode='r', attrs=SFTPAttrs(), encoding='utf-8', errors='strict')
   .. automethod:: truncate
   .. automethod:: rename
   .. automethod:: posix_rename
   .. automethod:: remove
   .. automethod:: unlink
   .. automethod:: readlink
   .. automethod:: symlink
   .. automethod:: link
   .. automethod:: realpath
   ========================================================================================== =

   ============================= =
   File attribute access methods
   ============================= =
   .. automethod:: stat
   .. automethod:: lstat
   .. automethod:: setstat
   .. automethod:: statvfs
   .. automethod:: chown
   .. automethod:: chmod
   .. automethod:: utime
   .. automethod:: exists
   .. automethod:: lexists
   .. automethod:: getatime
   .. automethod:: getmtime
   .. automethod:: getsize
   .. automethod:: isdir
   .. automethod:: isfile
   .. automethod:: islink
   ============================= =

   ============================================== =
   Directory access methods
   ============================================== =
   .. automethod:: chdir
   .. automethod:: getcwd
   .. automethod:: mkdir(path, attrs=SFTPAttrs())
   .. automethod:: rmdir
   .. automethod:: readdir
   .. automethod:: listdir
   .. automethod:: glob
   ============================================== =

   =========================== =
   Cleanup methods
   =========================== =
   .. automethod:: exit
   .. automethod:: wait_closed
   =========================== =

SFTPClientFile
--------------

.. autoclass:: SFTPClientFile()

   ================================================ =
   .. automethod:: read
   .. automethod:: write
   .. automethod:: seek(offset, from_what=SEEK_SET)
   .. automethod:: tell
   .. automethod:: stat
   .. automethod:: setstat
   .. automethod:: statvfs
   .. automethod:: truncate
   .. automethod:: chown
   .. automethod:: chmod
   .. automethod:: utime
   .. automethod:: fsync
   .. automethod:: close
   ================================================ =

SFTPServer
----------

.. autoclass:: SFTPServer

   ================================== =
   Path remapping and display methods
   ================================== =
   .. automethod:: format_user
   .. automethod:: format_group
   .. automethod:: format_longname
   .. automethod:: map_path
   .. automethod:: reverse_map_path
   ================================== =

   ============================ =
   File access methods
   ============================ =
   .. automethod:: open
   .. automethod:: close
   .. automethod:: read
   .. automethod:: write
   .. automethod:: rename
   .. automethod:: posix_rename
   .. automethod:: remove
   .. automethod:: readlink
   .. automethod:: symlink
   .. automethod:: link
   .. automethod:: realpath
   ============================ =

   ============================= =
   File attribute access methods
   ============================= =
   .. automethod:: stat
   .. automethod:: lstat
   .. automethod:: fstat
   .. automethod:: setstat
   .. automethod:: fsetstat
   .. automethod:: statvfs
   .. automethod:: fstatvfs
   ============================= =

   ======================== =
   Directory access methods
   ======================== =
   .. automethod:: listdir
   .. automethod:: mkdir
   .. automethod:: rmdir
   ======================== =

   ===================== =
   Cleanup methods
   ===================== =
   .. automethod:: exit
   ===================== =

SFTPAttrs
---------

.. autoclass:: SFTPAttrs()

SFTPVFSAttrs
------------

.. autoclass:: SFTPVFSAttrs()

SFTPName
--------

.. autoclass:: SFTPName()

.. index:: Public key and certificate support
.. _PublicKeySupport:

Public Key Support
==================

AsyncSSH has extensive public key and certificate support.

Supported public key types include DSA, RSA, and ECDSA. In addition,
Ed25519 keys are supported if the libnacl package and libsodium library
are installed.

Supported certificate types include OpenSSH version 01 certificates for
DSA, RSA, ECDSA, and Ed25519 keys and X.509 certificates for DSA, RSA,
and ECDSA keys.

Support is also available for the certificate critical options of
force-command and source-address and the extensions permit-X11-forwarding,
permit-agent-forwarding, permit-port-forwarding, and permit-pty in
OpenSSH certificates.

Several public key and certificate formats are supported including
PKCS#1 and PKCS#8 DER and PEM, OpenSSH, RFC4716, and X.509 DER and
PEM formats.

PEM and PKCS#8 password-based encryption of private keys is supported, as
is OpenSSH private key encryption when the bcrypt package is installed.

.. index:: Specifying private keys
.. _SpecifyingPrivateKeys:

Specifying private keys
-----------------------

Private keys may be passed into AsyncSSH in a variety of forms. The
simplest option is to pass the name of a file to read one or more
private keys from.

An alternate form involves passing in a list of values which can be
either a reference to a private key or a tuple containing a reference
to a private key and a reference to a corresponding certificate or
certificate chain.

Key references can either be the name of a file to load a key from,
a byte string to import as a key, or an already loaded :class:`SSHKey`
private key. See the function :func:`import_private_key` for the list
of supported private key formats.

Certificate references can be the name of a file to load a certificate
from, a byte string to import as a certificate, an already loaded
:class:`SSHCertificate`, or ``None`` if no certificate should be
associated with the key.

Whenever a filename is provided to read the private key from, an attempt
is made to load a corresponding certificate or certificate chain from a
file constructed by appending '-cert.pub' to the end of the name. X.509
certificates may also be provided in the same file as the private key,
when using DER or PEM format.

When using X.509 certificates, a list of certificates can also be
provided. These certificates should form a trust chain from a user or
host certificate up to some self-signed root certificate authority
which is trusted by the remote system.

New private keys can be generated using the :func:`generate_private_key`
function. The resulting :class:`SSHKey` objects have methods which can
then be used to export the generated keys in several formats for
consumption by other tools, as well as methods for generating new
OpenSSH or X.509 certificates.

.. index:: Specifying public keys
.. _SpecifyingPublicKeys:

Specifying public keys
----------------------

Public keys may be passed into AsyncSSH in a variety of forms. The
simplest option is to pass the name of a file to read one or more
public keys from.

An alternate form involves passing in a list of values each of which
can be either the name of a file to load a key from, a byte string
to import it from, or an already loaded :class:`SSHKey` public key.
See the function :func:`import_public_key` for the list of supported
public key formats.

.. index:: Specifying certificates
.. _SpecifyingCertificates:

Specifying certificates
-----------------------

Certificates may be passed into AsyncSSH in a variety of forms. The
simplest option is to pass the name of a file to read one or more
certificates from.

An alternate form involves passing in a list of values each of which
can be either the name of a file to load a certificate from, a byte string
to import it from, or an already loaded :class:`SSHCertificate` object.
See the function :func:`import_certificate` for the list of supported
certificate formats.

.. index:: Specifying X.509 subject names
.. _SpecifyingX509Subjects:

Specifying X.509 subject names
------------------------------

X.509 certificate subject names may be specified in place of public keys
or certificates in authorized_keys and known_hosts files, allowing any
X.509 certificate which matches that subject name to be considered a
known host or authorized key. The syntax supported for this is compatible
with PKIX-SSH, which adds X.509 certificate support to OpenSSH.

To specify a subject name pattern instead of a specific certificate,
base64-encoded certificate data should be replaced with the string
'Subject:' followed by a a comma-separated list of X.509 relative
distinguished name components.

AsyncSSH extends the PKIX-SSH syntax to also support matching on a
prefix of a subject name. To indicate this, a partial subject name
can be specified which ends in ',*'.  Any subject which matches the
relative distinguished names listed before the ",*" will be treated
as a match, even if the certificate provided has additional relative
distinguished names following what was matched.

.. index:: Specifying X.509 purposes
.. _SpecifyingX509Purposes:

Specifying X.509 purposes
-------------------------

When performing X.509 certificate authentication, AsyncSSH can be
passed in an allowed set of ExtendedKeyUsage purposes. Purposes are
matched in X.509 certificates as OID values, but AsyncSSH also allows
the following well-known purpose values to be specified by name:

  ================= ==================
  Name              OID
  ================= ==================
  serverAuth        1.3.6.1.5.5.7.3.1
  clientAuth        1.3.6.1.5.5.7.3.2
  secureShellClient 1.3.6.1.5.5.7.3.20
  secureShellServer 1.3.6.1.5.5.7.3.21
  ================= ==================

Values not in the list above can be specified directly by OID as a
dotted numeric string value. Either a single value or a list of values
can be provided.

The check succeeds if any of the specified values are present in the
certificate's ExtendedKeyUsage. It will also succeed if the certificate
does not contain an ExtendedKeyUsage or if the ExtendedKeyUsage contains
the OID 2.5.29.37.0, which indicates the certificate can be used for any
purpose.

This check defaults to requiring a purpose of 'secureShellCient' for
client certificates and 'secureShellServer' for server certificates
and should not normally need to be changed. However, certificates which
contain other purposes can be supported by providing alternate values to
match against, or by passing in the purpose 'any' to disable this checking.

.. index:: Specifying time values
.. _SpecifyingTimeValues:

Specifying time values
----------------------

When generating certificates, an optional validity interval can be
specified using the ``valid_after`` and ``valid_before`` parameters
to the :meth:`generate_user_certificate() <SSHKey.generate_user_certificate>`
and :meth:`generate_host_certificate() <SSHKey.generate_host_certificate>`
methods. These values can be specified in any of the following ways:

    * An int or float UNIX epoch time, such as what is returned by
      :func:`time.time`.
    * A :class:`datetime.datetime` value.
    * A string value of ``now`` to request the current time.
    * A string value in the form ``YYYYMMDD`` to specify an absolute date.
    * A string value in the form ``YYYYMMDDHHMMSS`` to specify an
      absolute date and time.
    * A relative time made up of a mix of positive or negative numbers and
      the letters 'w', 'd', 'h', 'm', and 's', representing an offset from
      the current time in weeks, days, hours, minutes, or seconds,
      respectively. Multiple of these values can be included. For
      instance, '+1w2d3h' means 1 week, 2 days, and 3 hours in the future.

SSHKey
------

.. autoclass:: SSHKey()

   ============================================== =
   .. automethod:: get_algorithm
   .. automethod:: get_comment
   .. automethod:: set_comment
   .. automethod:: convert_to_public
   .. automethod:: generate_user_certificate
   .. automethod:: generate_host_certificate
   .. automethod:: generate_x509_user_certificate
   .. automethod:: generate_x509_host_certificate
   .. automethod:: generate_x509_ca_certificate
   .. automethod:: export_private_key
   .. automethod:: export_public_key
   .. automethod:: write_private_key
   .. automethod:: write_public_key
   .. automethod:: append_private_key
   .. automethod:: append_public_key
   ============================================== =

SSHKeyPair
----------

.. autoclass:: SSHKeyPair()

   ============================= =
   .. automethod:: get_key_type
   .. automethod:: get_algorithm
   .. automethod:: get_comment
   .. automethod:: set_comment
   ============================= =

SSHCertificate
--------------

.. autoclass:: SSHCertificate()

   ================================== =
   .. automethod:: get_algorithm
   .. automethod:: get_comment
   .. automethod:: set_comment
   .. automethod:: export_certificate
   .. automethod:: write_certificate
   .. automethod:: append_certificate
   ================================== =

generate_private_key
--------------------

.. autofunction:: generate_private_key

import_private_key
------------------

.. autofunction:: import_private_key

import_public_key
-----------------

.. autofunction:: import_public_key

import_certificate
------------------

.. autofunction:: import_certificate

read_private_key
----------------

.. autofunction:: read_private_key

read_public_key
---------------

.. autofunction:: read_public_key

read_certificate
----------------

.. autofunction:: read_certificate

read_private_key_list
---------------------

.. autofunction:: read_private_key_list

read_public_key_list
--------------------

.. autofunction:: read_public_key_list

read_certificate_list
---------------------

.. autofunction:: read_certificate_list

load_keypairs
-------------

.. autofunction:: load_keypairs

load_public_keys
----------------

.. autofunction:: load_public_keys

load_certificates
-----------------

.. autofunction:: load_certificates

.. index:: SSH agent support

SSH Agent Support
=================

AsyncSSH supports the ability to use private keys managed by the OpenSSH
ssh-agent on UNIX systems. It can connect via a UNIX domain socket to
the agent and offload all private key operations to it, avoiding the need
to read these keys into AsyncSSH itself. An ssh-agent is automatically
used in :func:`create_connection` when a valid ``SSH_AUTH_SOCK`` is set
in the environment. An alternate path to the agent can be specified via
the ``agent_path`` argument to this function.

An ssh-agent can also be accessed directly from AsyncSSH by calling
:func:`connect_agent`. When successful, this function returns an
:class:`SSHAgentClient` which can be used to get a list of available
keys, add and remove keys, and lock and unlock access to this agent.

SSH agent forwarding may be enabled when making outbound SSH connections
by specifying the ``agent_forwarding`` argument when calling
:func:`create_connection`, allowing processes running on the server
to tunnel requests back over the SSH connection to the client's ssh-agent.

Agent forwarding can be enabled when starting an SSH server by
specifying the ``agent_forwarding`` argument when calling
:func:`create_server`. In this case, the client's ssh-agent can be
accessed from the server by passing the :class:`SSHServerConnection` as
the argument to :func:`connect_agent` instead of a local path. Alternately,
when an :class:`SSHServerChannel` has been opened, the :meth:`get_agent_path()
<SSHServerChannel.get_agent_path>` method may be called on it to get a
path to a UNIX domain socket which can be passed as the ``SSH_AUTH_SOCK``
to local applications which need this access. Any requests sent to this
socket are forwarded over the SSH connection to the client's ssh-agent.

SSHAgentClient
--------------

.. autoclass:: SSHAgentClient()

   ===================================== =
   .. automethod:: get_keys
   .. automethod:: add_keys
   .. automethod:: add_smartcard_keys
   .. automethod:: remove_keys
   .. automethod:: remove_smartcard_keys
   .. automethod:: remove_all
   .. automethod:: lock
   .. automethod:: unlock
   .. automethod:: query_extensions
   .. automethod:: close
   ===================================== =

SSHAgentKeyPair
---------------

.. autoclass:: SSHAgentKeyPair()

   ============================= =
   .. automethod:: get_key_type
   .. automethod:: get_algorithm
   .. automethod:: get_comment
   .. automethod:: set_comment
   .. automethod:: remove
   ============================= =

connect_agent
-------------

.. autofunction:: connect_agent

.. index:: Known hosts
.. _KnownHosts:

Known Hosts
===========

AsyncSSH supports OpenSSH-style known_hosts files, including both
plain and hashed host entries. Regular and negated host patterns are
supported in plain entries. AsyncSSH also supports the ``@cert_authority``
marker to indicate keys and certificates which should be trusted as
certificate authorities and the ``@revoked`` marker to indicate keys and
certificates which should be explicitly reported as no longer trusted.

.. index:: Specifying known hosts
.. _SpecifyingKnownHosts:

Specifying known hosts
----------------------

Known hosts may be passed into AsyncSSH via the ``known_hosts`` argument
to :func:`create_connection`. This can be the name of a file containing
a list of known hosts, a byte string containing a list of known hosts,
or an :class:`SSHKnownHosts` object which was previously imported from
a string by calling :func:`import_known_hosts` or read from a file by
calling :func:`read_known_hosts`. In all of these cases, the host patterns
in the list will be compared against the target host, address, and port
being connected to and the matching trusted host keys, trusted CA keys,
revoked keys, trusted X.509 certificates, revoked X.509 certificates,
trusted X.509 subject names, and revoked X.509 subject names will be
returned.

Alternately, a function can be passed in as the ``known_hosts`` argument
that accepts a target host, address, and port and returns lists containing
trusted host keys, trusted CA keys, revoked keys, trusted X.509 certificates,
revoked X.509 certificates, trusted X.509 subject names, and revoked X.509
subject names.

If no matching is required and the caller already knows exactly what the
above values should be, these seven lists can also be provided directly in
the ``known_hosts`` argument.

See :ref:`SpecifyingPublicKeys` for the allowed form of public key values
which can be provided, :ref:`SpecifyingCertificates` for the allowed form
of certificates, and :ref:`SpecifyingX509Subjects` for the allowed form
of X.509 subject names.

SSHKnownHosts
-------------

.. autoclass:: SSHKnownHosts()

   ===================== =
   .. automethod:: match
   ===================== =

import_known_hosts
------------------

.. autofunction:: import_known_hosts

read_known_hosts
----------------

.. autofunction:: read_known_hosts


match_known_hosts
-----------------

.. autofunction:: match_known_hosts

.. index:: Authorized keys
.. _AuthorizedKeys:

Authorized Keys
===============

AsyncSSH supports OpenSSH-style authorized_keys files, including the
cert-authority option to validate user certificates, enforcement of
from and principals options to restrict key matching, enforcement
of no-X11-forwarding, no-agent-forwarding, no-pty, no-port-forwarding,
and permitopen options, and support for command and environment options.

.. index:: Specifying authorized keys
.. _SpecifyingAuthorizedKeys:

Specifying authorized keys
--------------------------

Authorized keys may be passed into AsyncSSH via the
``authorized_client_keys`` argument to :func:`create_server` or by calling
:meth:`set_authorized_keys() <SSHServerConnection.set_authorized_keys>`
on the :class:`SSHServerConnection` from within the :meth:`begin_auth()
<SSHServer.begin_auth>` method in :class:`SSHServer`.

Authorized keys can be provided as either the name of a file to read
the keys from or an :class:`SSHAuthorizedKeys` object which was previously
imported from a string by calling :func:`import_authorized_keys` or read
from a file by calling :func:`read_authorized_keys`.

An authorized keys file may contain public keys or X.509 certificates
in OpenSSH format or X.509 certificate subject names. See
:ref:`SpecifyingX509Subjects` for more information on using subject names
in place of specific X.509 certificates.

SSHAuthorizedKeys
-----------------

.. autoclass:: SSHAuthorizedKeys()

import_authorized_keys
----------------------

.. autofunction:: import_authorized_keys

read_authorized_keys
--------------------

.. autofunction:: read_authorized_keys

.. index:: Exceptions
.. _Exceptions:

Exceptions
==========

PasswordChangeRequired
----------------------

.. autoexception:: PasswordChangeRequired

BreakReceived
-------------

.. autoexception:: BreakReceived

SignalReceived
--------------

.. autoexception:: SignalReceived

TerminalSizeChanged
-------------------

.. autoexception:: TerminalSizeChanged

DisconnectError
---------------

.. autoexception:: DisconnectError

ChannelOpenError
----------------

.. autoexception:: ChannelOpenError

ProcessError
------------

.. autoexception:: ProcessError

SFTPError
---------

.. autoexception:: SFTPError

KeyImportError
--------------

.. autoexception:: KeyImportError

KeyExportError
--------------

.. autoexception:: KeyExportError

KeyEncryptionError
------------------

.. autoexception:: KeyEncryptionError

KeyGenerationError
------------------

.. autoexception:: KeyGenerationError

.. index:: Supported algorithms
.. _SupportedAlgorithms:

Supported Algorithms
====================

.. index:: Key exchange algorithms
.. _KexAlgs:

Key exchange algorithms
-----------------------

The following are the key exchange algorithms currently supported by AsyncSSH:

  | gss-gex-sha256
  | gss-gex-sha1
  | gss-group1-sha1
  | gss-group14-sha1
  | gss-group14-sha256
  | gss-group15-sha512
  | gss-group16-sha512
  | gss-group17-sha512
  | gss-group18-sha512
  | curve25519-sha256
  | curve25519-sha256\@libssh.org
  | ecdh-sha2-nistp521
  | ecdh-sha2-nistp384
  | ecdh-sha2-nistp256
  | diffie-hellman-group-exchange-sha256
  | diffie-hellman-group-exchange-sha1
  | diffie-hellman-group1-sha1
  | diffie-hellman-group14-sha1
  | diffie-hellman-group14-sha256
  | diffie-hellman-group15-sha512
  | diffie-hellman-group16-sha512
  | diffie-hellman-group17-sha512
  | diffie-hellman-group18-sha512

Curve25519 support is only available when the libnacl package and libsodium
library are installed.

GSS authentication support is only available when the gssapi package is
installed on UNIX or the pypiwin32 package is installed on Windows.

.. index:: Encryption algorithms
.. _EncryptionAlgs:

Encryption algorithms
---------------------

The following are the encryption algorithms currently supported by AsyncSSH:

  | chacha20-poly1305\@openssh.com
  | aes256-ctr
  | aes192-ctr
  | aes128-ctr
  | aes256-gcm\@openssh.com
  | aes128-gcm\@openssh.com
  | aes256-cbc
  | aes192-cbc
  | aes128-cbc
  | 3des-cbc
  | blowfish-cbc
  | cast128-cbc
  | arcfour256
  | arcfour128
  | arcfour

Chacha20-poly1305 support is only available when the libnacl package and
libsodium library are installed.

.. index:: MAC algorithms
.. _MACAlgs:

MAC algorithms
--------------

The following are the MAC algorithms currently supported by AsyncSSH:

  | umac-64-etm\@openssh.com
  | umac-128-etm\@openssh.com
  | hmac-sha2-256-etm\@openssh.com
  | hmac-sha2-512-etm\@openssh.com
  | hmac-sha1-etm\@openssh.com
  | hmac-md5-etm\@openssh.com
  | hmac-sha2-256-96-etm\@openssh.com
  | hmac-sha2-512-96-etm\@openssh.com
  | hmac-sha1-96-etm\@openssh.com
  | hmac-md5-96-etm\@openssh.com
  | umac-64\@openssh.com
  | umac-128\@openssh.com
  | hmac-sha2-256
  | hmac-sha2-512
  | hmac-sha1
  | hmac-md5
  | hmac-sha2-256-96
  | hmac-sha2-512-96
  | hmac-sha1-96
  | hmac-md5-96

UMAC support is only available when the nettle library is installed.

.. index:: Compression algorithms
.. _CompressionAlgs:

Compression algorithms
----------------------

The following are the compression algorithms currently supported by AsyncSSH:

  | zlib\@openssh.com
  | zlib
  | none

.. index:: Signature algorithms
.. _SignatureAlgs:

Signature algorithms
--------------------

The following are the public key signature algorithms currently supported by
AsyncSSH:

  | x509v3-ecdsa-sha2-nistp521
  | x509v3-ecdsa-sha2-nistp384
  | x509v3-ecdsa-sha2-nistp256
  | x509v3-rsa2048-sha256
  | x509v3-ssh-rsa
  | x509v3-ssh-dss
  | ssh-ed25519
  | ecdsa-sha2-nistp521
  | ecdsa-sha2-nistp384
  | ecdsa-sha2-nistp256
  | rsa-sha2-256
  | rsa-sha2-512
  | ssh-rsa
  | ssh-dss

.. index:: Public key & certificate algorithms
.. _PublicKeyAlgs:

Public key & certificate algorithms
-----------------------------------

The following are the public key and certificate algorithms currently
supported by AsyncSSH:

  | x509v3-ecdsa-sha2-nistp521
  | x509v3-ecdsa-sha2-nistp384
  | x509v3-ecdsa-sha2-nistp256
  | x509v3-rsa2048-sha256
  | x509v3-ssh-rsa
  | x509v3-ssh-dss
  | ssh-ed25519-cert-v01\@openssh.com
  | ecdsa-sha2-nistp521-cert-v01\@openssh.com
  | ecdsa-sha2-nistp384-cert-v01\@openssh.com
  | ecdsa-sha2-nistp256-cert-v01\@openssh.com
  | ssh-rsa-cert-v01\@openssh.com
  | ssh-dss-cert-v01\@openssh.com
  | ssh-ed25519
  | ecdsa-sha2-nistp521
  | ecdsa-sha2-nistp384
  | ecdsa-sha2-nistp256
  | rsa-sha2-256
  | rsa-sha2-512
  | ssh-rsa
  | ssh-dss

Ed25519 support is only available when the libnacl package and libsodium
library are installed.

.. index:: Constants
.. _Constants:

Constants
=========

.. index:: Disconnect reasons
.. _DisconnectReasons:

Disconnect reasons
------------------

The following values defined in section 11.1 of :rfc:`4253#section-11.1`
can be specified as disconnect reason codes:

  | DISC_HOST_NOT_ALLOWED_TO_CONNECT
  | DISC_PROTOCOL_ERROR
  | DISC_KEY_EXCHANGE_FAILED
  | DISC_RESERVED
  | DISC_MAC_ERROR
  | DISC_COMPRESSION_ERROR
  | DISC_SERVICE_NOT_AVAILABLE
  | DISC_PROTOCOL_VERSION_NOT_SUPPORTED
  | DISC_HOST_KEY_NOT_VERIFYABLE
  | DISC_CONNECTION_LOST
  | DISC_BY_APPLICATION
  | DISC_TOO_MANY_CONNECTIONS
  | DISC_AUTH_CANCELLED_BY_USER
  | DISC_NO_MORE_AUTH_METHODS_AVAILABLE
  | DISC_ILLEGAL_USER_NAME

.. index:: Channel open failure reasons
.. _ChannelOpenFailureReasons:

Channel open failure reasons
----------------------------

The following values defined in section 5.1 of :rfc:`4254#section-5.1` can
be specified as channel open failure reason codes:

  | OPEN_ADMINISTRATIVELY_PROHIBITED
  | OPEN_CONNECT_FAILED
  | OPEN_UNKNOWN_CHANNEL_TYPE
  | OPEN_RESOURCE_SHORTAGE

In addition, AsyncSSH defines the following channel open failure reason codes:

  | OPEN_REQUEST_X11_FORWARDING_FAILED
  | OPEN_REQUEST_PTY_FAILED
  | OPEN_REQUEST_SESSION_FAILED

.. index:: SFTP error codes
.. _SFTPErrorCodes:

SFTP error codes
----------------

The following values defined in the `SSH File Transfer Internet Draft
<http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt>`_ can be
specified as SFTP error codes:

  | FX_OK
  | FX_EOF
  | FX_NO_SUCH_FILE
  | FX_PERMISSION_DENIED
  | FX_FAILURE
  | FX_BAD_MESSAGE
  | FX_NO_CONNECTION
  | FX_CONNECTION_LOST
  | FX_OP_UNSUPPORTED

.. index:: Extended data types
.. _ExtendedDataTypes:

Extended data types
-------------------

The following values defined in section 5.2 of :rfc:`4254#section-5.2` can
be specified as SSH extended channel data types:

  | EXTENDED_DATA_STDERR

.. index:: POSIX terminal modes
.. _PTYModes:

POSIX terminal modes
--------------------

The following values defined in section 8 of :rfc:`4254#section-8` can be
specified as PTY mode opcodes:

  | PTY_OP_END
  | PTY_VINTR
  | PTY_VQUIT
  | PTY_VERASE
  | PTY_VKILL
  | PTY_VEOF
  | PTY_VEOL
  | PTY_VEOL2
  | PTY_VSTART
  | PTY_VSTOP
  | PTY_VSUSP
  | PTY_VDSUSP
  | PTY_VREPRINT
  | PTY_WERASE
  | PTY_VLNEXT
  | PTY_VFLUSH
  | PTY_VSWTCH
  | PTY_VSTATUS
  | PTY_VDISCARD
  | PTY_IGNPAR
  | PTY_PARMRK
  | PTY_INPCK
  | PTY_ISTRIP
  | PTY_INLCR
  | PTY_IGNCR
  | PTY_ICRNL
  | PTY_IUCLC
  | PTY_IXON
  | PTY_IXANY
  | PTY_IXOFF
  | PTY_IMAXBEL
  | PTY_ISIG
  | PTY_ICANON
  | PTY_XCASE
  | PTY_ECHO
  | PTY_ECHOE
  | PTY_ECHOK
  | PTY_ECHONL
  | PTY_NOFLSH
  | PTY_TOSTOP
  | PTY_IEXTEN
  | PTY_ECHOCTL
  | PTY_ECHOKE
  | PTY_PENDIN
  | PTY_OPOST
  | PTY_OLCUC
  | PTY_ONLCR
  | PTY_OCRNL
  | PTY_ONOCR
  | PTY_ONLRET
  | PTY_CS7
  | PTY_CS8
  | PTY_PARENB
  | PTY_PARODD
  | PTY_OP_ISPEED
  | PTY_OP_OSPEED
