SSH agents — Paramiko documentation

# SSH agents

SSH Agent interface

class `paramiko.agent.` `Agent`

  Client interface for using private keys from an SSH agent running on the local machine. If an SSH agent is running, this class can be used to connect to it and retreive `PKey` objects which can be used when attempting to authenticate to remote SSH servers.

  Upon initialization, a session with the local machine’s SSH agent is opened, if one is running. If no agent is running, initialization will succeed, but `get_keys` will return an empty tuple.

  Raises SSHException:
  | if an SSH agent is found, but speaks an incompatible protocol

  `close`()

    Close the SSH agent connection.

  `get_keys`()

    Return the list of keys available through the SSH agent, if any. If no SSH agent was running (or it couldn’t be contacted), an empty list will be returned.

    Returns: | a tuple of `AgentKey` objects representing keys available on the SSH agent

class `paramiko.agent.` `AgentClientProxy`(chanRemote)

  Class proxying request as a client:

  1. client ask for a request_forward_agent()
  2. server creates a proxy and a fake SSH Agent
  3. server ask for establishing a connection when needed, calling the forward_agent_handler at client side.
  4. the forward_agent_handler launch a thread for connecting the remote fake agent and the local agent
  5. Communication occurs ...
  `close`()

    Close the current connection and terminate the agent Should be called manually

  `connect`()

    Method automatically called by `AgentProxyThread.run`.

class `paramiko.agent.` `AgentKey`(agent, blob)

  Private key held in a local SSH agent. This type of key can be used for authenticating to a remote server (signing). Most other key operations work as expected.

  `can_sign`()

    Return `True` if this key has the private part necessary for signing data.

  `from_private_key`(file_obj, password=None)

    Create a key object by reading a private key from a file (or file-like) object. If the private key is encrypted and `password` is not `None`, the given password will be used to decrypt the key (otherwise `PasswordRequiredException` is thrown).

    Parameters: | file_obj – the file-like object to read from password (str) – an optional password to use to decrypt the key, if it’s encrypted
    Returns: | a new `PKey` based on the given private key
    Raises: | IOError – if there was an error reading the key PasswordRequiredException – if the private key file is encrypted, and `password` is `None` SSHException – if the key file is invalid

  `from_private_key_file`(filename, password=None)

    Create a key object by reading a private key file. If the private key is encrypted and `password` is not `None`, the given password will be used to decrypt the key (otherwise `PasswordRequiredException` is thrown). Through the magic of Python, this factory method will exist in all subclasses of PKey (such as `RSAKey` or `DSSKey`), but is useless on the abstract PKey class.

    Parameters: | filename (str) – name of the file to read password (str) – an optional password to use to decrypt the key file, if it’s encrypted
    Returns: | a new `PKey` based on the given private key
    Raises: | IOError – if there was an error reading the file PasswordRequiredException – if the private key file is encrypted, and `password` is `None` SSHException – if the key file is invalid

  `get_base64`()

    Return a base64 string containing the public part of this key. Nothing secret is revealed. This format is compatible with that used to store public key files or recognized host keys.

    Returns: | a base64 `string` containing the public part of the key.

  `get_bits`()

    Return the number of significant bits in this key. This is useful for judging the relative security of a key.

    Returns: | bits in the key (as an `int`)

  `get_fingerprint`()

    Return an MD5 fingerprint of the public part of this key. Nothing secret is revealed.

    Returns: | a 16-byte `string` (binary) of the MD5 fingerprint, in SSH format.

  `verify_ssh_sig`(data, msg)

    Given a blob of data, and an SSH message representing a signature of that data, verify that it was signed with this key.

    Parameters: | data (str) – the data that was signed. msg (Message) – an SSH signature message
    Returns: | `True` if the signature verifies correctly; `False` otherwise.

  `write_private_key`(file_obj, password=None)

    Write private key contents into a file (or file-like) object. If the password is not `None`, the key is encrypted before writing.

    Parameters: | file_obj – the file-like object to write into password (str) – an optional password to use to encrypt the key
    Raises: | IOError – if there was an error writing to the file SSHException – if the key is invalid

  `write_private_key_file`(filename, password=None)

    Write private key contents into a file. If the password is not `None`, the key is encrypted before writing.

    Parameters: | filename (str) – name of the file to write password (str) – an optional password to use to encrypt the key file
    Raises: | IOError – if there was an error writing the file SSHException – if the key is invalid

class `paramiko.agent.` `AgentLocalProxy`(agent)

  Class to be used when wanting to ask a local SSH Agent being asked from a remote fake agent (so use a unix socket for ex.)

  `get_connection`()

    Return a pair of socket object and string address.

    May block!

class `paramiko.agent.` `AgentProxyThread`(agent)

  Class in charge of communication between two channels.

class `paramiko.agent.` `AgentRemoteProxy`(agent, chan)

  Class to be used when wanting to ask a remote SSH Agent

class `paramiko.agent.` `AgentRequestHandler`(chanClient)

  Primary/default implementation of SSH agent forwarding functionality.

  Simply instantiate this class, handing it a live command-executing session object, and it will handle forwarding any local SSH agent processes it finds.

  For example:

      # Connect
      client = SSHClient()
      client.connect(host, port, username)
      # Obtain session
      session = client.get_transport().open_session()
      # Forward local agent
      AgentRequestHandler(session)
      # Commands executed after this point will see the forwarded agent on
      # the remote end.
      session.exec_command("git clone https://my.git.repository/")

class `paramiko.agent.` `AgentServerProxy`(t)

  Parameters: | t (Transport) – Transport used for SSH Agent communication forwarding
  Raises SSHException:
  | mostly if we lost the agent

  `close`()

    Terminate the agent, clean the files, close connections Should be called manually

  `get_env`()

    Helper for the environnement under unix

    Returns: | a dict containing the `SSH_AUTH_SOCK` environnement variables

  `get_keys`()

    Return the list of keys available through the SSH agent, if any. If no SSH agent was running (or it couldn’t be contacted), an empty list will be returned.

    Returns: | a tuple of `AgentKey` objects representing keys available on the SSH agent