GSS-API authentication — Paramiko documentation

# GSS-API authentication

This module provides GSS-API / SSPI authentication as defined in RFC 4462.

Note

Credential delegation is not supported in server mode.

See also

GSS-API key exchange

New in version 1.15.

paramiko.ssh_gss.GSS_AUTH_AVAILABLE = False

  A boolean constraint that indicates if GSS-API / SSPI is available.

paramiko.ssh_gss.GSS_EXCEPTIONS = ()

  A tuple of the exception types used by the underlying GSSAPI implementation.

paramiko.ssh_gss.GSSAuth(auth_method, gss_deleg_creds=True)

  Provide SSH2 GSS-API / SSPI authentication.

  Parameters

    - auth_method (str) – The name of the SSH authentication mechanism (gssapi-with-mic or gss-keyex)

    - gss_deleg_creds (bool) – Delegate client credentials or not. We delegate credentials by default.

  Returns

    Either an `_SSH_GSSAPI_OLD` or `_SSH_GSSAPI_NEW` (Unix) object or an `_SSH_SSPI` (Windows) object

  Return type

    object

  Raises

    `ImportError` – If no GSS-API / SSPI module could be imported.

  See

    RFC 4462

  Note

    Check for the available API and return either an `_SSH_GSSAPI_OLD` (MIT GSSAPI using python-gssapi package) object, an `_SSH_GSSAPI_NEW` (MIT GSSAPI using gssapi package) object or an `_SSH_SSPI` (MS SSPI) object. If there is no supported API available, `None` will be returned.

class paramiko.ssh_gss._SSH_GSSAuth(auth_method, gss_deleg_creds)

  Contains the shared variables and methods of `_SSH_GSSAPI_OLD`, `_SSH_GSSAPI_NEW` and `_SSH_SSPI`.

  __init__(auth_method, gss_deleg_creds)
    Parameters

      - auth_method (str) – The name of the SSH authentication mechanism (gssapi-with-mic or gss-keyex)

      - gss_deleg_creds (bool) – Delegate client credentials or not

  set_service(service)

    This is just a setter to use a non default service. I added this method, because RFC 4462 doesn’t specify “ssh-connection” as the only service value.

    Parameters

      service (str) – The desired SSH service

  set_username(username)

    Setter for C{username}. If GSS-API Key Exchange is performed, the username is not set by C{ssh_init_sec_context}.

    Parameters

      username (str) – The name of the user who attempts to login

  ssh_gss_oids(mode='client')

    This method returns a single OID, because we only support the Kerberos V5 mechanism.

    Parameters

      mode (str) – Client for client mode and server for server mode

    Returns

      A byte sequence containing the number of supported OIDs, the length of the OID and the actual OID encoded with DER

    Note

      In server mode we just return the OID length and the DER encoded OID.

  ssh_check_mech(desired_mech)

    Check if the given OID is the Kerberos V5 OID (server mode).

    Parameters

      desired_mech (str) – The desired GSS-API mechanism of the client

    Returns

      `True` if the given OID is supported, otherwise C{False}

  __weakref__

    list of weak references to the object (if defined)

class paramiko.ssh_gss._SSH_GSSAPI_OLD(auth_method, gss_deleg_creds)

  Implementation of the GSS-API MIT Kerberos Authentication for SSH2, using the older (unmaintained) python-gssapi package.

  See

    `GSSAuth`

  __init__(auth_method, gss_deleg_creds)
    Parameters

      - auth_method (str) – The name of the SSH authentication mechanism (gssapi-with-mic or gss-keyex)

      - gss_deleg_creds (bool) – Delegate client credentials or not

  ssh_init_sec_context(target, desired_mech=None, username=None, recv_token=None)

    Initialize a GSS-API context.

    Parameters

      - username (str) – The name of the user who attempts to login

      - target (str) – The hostname of the target to connect to

      - desired_mech (str) – The negotiated GSS-API mechanism (“pseudo negotiated” mechanism, because we support just the krb5 mechanism :-))

      - recv_token (str) – The GSS-API token received from the Server

    Raises

      `SSHException` – Is raised if the desired mechanism of the client is not supported

    Returns

      A `String` if the GSS-API has returned a token or `None` if no token was returned

  ssh_get_mic(session_id, gss_kex=False)

    Create the MIC token for a SSH2 message.

    Parameters

      - session_id (str) – The SSH session ID

      - gss_kex (bool) – Generate the MIC for GSS-API Key Exchange or not

    Returns

      gssapi-with-mic: Returns the MIC token from GSS-API for the message we created with `_ssh_build_mic`. gssapi-keyex: Returns the MIC token from GSS-API with the SSH session ID as message.

  ssh_accept_sec_context(hostname, recv_token, username=None)

    Accept a GSS-API context (server mode).

    Parameters

      - hostname (str) – The servers hostname

      - username (str) – The name of the user who attempts to login

      - recv_token (str) – The GSS-API Token received from the server, if it’s not the initial call.

    Returns

      A `String` if the GSS-API has returned a token or `None` if no token was returned

  ssh_check_mic(mic_token, session_id, username=None)

    Verify the MIC token for a SSH2 message.

    Parameters

      - mic_token (str) – The MIC token received from the client

      - session_id (str) – The SSH session ID

      - username (str) – The name of the user who attempts to login

    Returns

      None if the MIC check was successful

    Raises

      `gssapi.GSSException` – if the MIC check failed

  property credentials_delegated

    Checks if credentials are delegated (server mode).

    Returns

      `True` if credentials are delegated, otherwise `False`

  save_client_creds(client_token)

    Save the Client token in a file. This is used by the SSH server to store the client credentials if credentials are delegated (server mode).

    Parameters

      client_token (str) – The GSS-API token received form the client

    Raises

      `NotImplementedError` – Credential delegation is currently not supported in server mode

class paramiko.ssh_gss._SSH_GSSAPI_NEW(auth_method, gss_deleg_creds)

  Implementation of the GSS-API MIT Kerberos Authentication for SSH2, using the newer, currently maintained gssapi package.

  See

    `GSSAuth`

  __init__(auth_method, gss_deleg_creds)
    Parameters

      - auth_method (str) – The name of the SSH authentication mechanism (gssapi-with-mic or gss-keyex)

      - gss_deleg_creds (bool) – Delegate client credentials or not

  ssh_init_sec_context(target, desired_mech=None, username=None, recv_token=None)

    Initialize a GSS-API context.

    Parameters

      - username (str) – The name of the user who attempts to login

      - target (str) – The hostname of the target to connect to

      - desired_mech (str) – The negotiated GSS-API mechanism (“pseudo negotiated” mechanism, because we support just the krb5 mechanism :-))

      - recv_token (str) – The GSS-API token received from the Server

    Raises

      `SSHException` – Is raised if the desired mechanism of the client is not supported

    Raises

      `gssapi.exceptions.GSSError` if there is an error signaled by the GSS-API implementation

    Returns

      A `String` if the GSS-API has returned a token or `None` if no token was returned

  ssh_get_mic(session_id, gss_kex=False)

    Create the MIC token for a SSH2 message.

    Parameters

      - session_id (str) – The SSH session ID

      - gss_kex (bool) – Generate the MIC for GSS-API Key Exchange or not

    Returns

      gssapi-with-mic: Returns the MIC token from GSS-API for the message we created with `_ssh_build_mic`. gssapi-keyex: Returns the MIC token from GSS-API with the SSH session ID as message.

    Return type

      str

  ssh_accept_sec_context(hostname, recv_token, username=None)

    Accept a GSS-API context (server mode).

    Parameters

      - hostname (str) – The servers hostname

      - username (str) – The name of the user who attempts to login

      - recv_token (str) – The GSS-API Token received from the server, if it’s not the initial call.

    Returns

      A `String` if the GSS-API has returned a token or `None` if no token was returned

  ssh_check_mic(mic_token, session_id, username=None)

    Verify the MIC token for a SSH2 message.

    Parameters

      - mic_token (str) – The MIC token received from the client

      - session_id (str) – The SSH session ID

      - username (str) – The name of the user who attempts to login

    Returns

      None if the MIC check was successful

    Raises

      `gssapi.exceptions.GSSError` – if the MIC check failed

  property credentials_delegated

    Checks if credentials are delegated (server mode).

    Returns

      `True` if credentials are delegated, otherwise `False`

    Return type

      bool

  save_client_creds(client_token)

    Save the Client token in a file. This is used by the SSH server to store the client credentials if credentials are delegated (server mode).

    Parameters

      client_token (str) – The GSS-API token received form the client

    Raises

      `NotImplementedError` – Credential delegation is currently not supported in server mode

class paramiko.ssh_gss._SSH_SSPI(auth_method, gss_deleg_creds)

  Implementation of the Microsoft SSPI Kerberos Authentication for SSH2.

  See

    `GSSAuth`

  __init__(auth_method, gss_deleg_creds)
    Parameters

      - auth_method (str) – The name of the SSH authentication mechanism (gssapi-with-mic or gss-keyex)

      - gss_deleg_creds (bool) – Delegate client credentials or not

  ssh_init_sec_context(target, desired_mech=None, username=None, recv_token=None)

    Initialize a SSPI context.

    Parameters

      - username (str) – The name of the user who attempts to login

      - target (str) – The FQDN of the target to connect to

      - desired_mech (str) – The negotiated SSPI mechanism (“pseudo negotiated” mechanism, because we support just the krb5 mechanism :-))

      - recv_token – The SSPI token received from the Server

    Raises

      `SSHException` – Is raised if the desired mechanism of the client is not supported

    Returns

      A `String` if the SSPI has returned a token or `None` if no token was returned

  ssh_get_mic(session_id, gss_kex=False)

    Create the MIC token for a SSH2 message.

    Parameters

      - session_id (str) – The SSH session ID

      - gss_kex (bool) – Generate the MIC for Key Exchange with SSPI or not

    Returns

      gssapi-with-mic: Returns the MIC token from SSPI for the message we created with `_ssh_build_mic`. gssapi-keyex: Returns the MIC token from SSPI with the SSH session ID as message.

  ssh_accept_sec_context(hostname, username, recv_token)

    Accept a SSPI context (server mode).

    Parameters

      - hostname (str) – The servers FQDN

      - username (str) – The name of the user who attempts to login

      - recv_token (str) – The SSPI Token received from the server, if it’s not the initial call.

    Returns

      A `String` if the SSPI has returned a token or `None` if no token was returned

  ssh_check_mic(mic_token, session_id, username=None)

    Verify the MIC token for a SSH2 message.

    Parameters

      - mic_token (str) – The MIC token received from the client

      - session_id (str) – The SSH session ID

      - username (str) – The name of the user who attempts to login

    Returns

      None if the MIC check was successful

    Raises

      `sspi.error` – if the MIC check failed

  property credentials_delegated

    Checks if credentials are delegated (server mode).

    Returns

      `True` if credentials are delegated, otherwise `False`

  save_client_creds(client_token)

    Save the Client token in a file. This is used by the SSH server to store the client credentails if credentials are delegated (server mode).

    Parameters

      client_token (str) – The SSPI token received form the client

    Raises

      `NotImplementedError` – Credential delegation is currently not supported in server mode