libssh: The SSH authentication functions

libssh 0.11.2 The SSH library

Loading...
Searching...
No Matches
The SSH authentication functions
The libssh API

## Typedefs
typedef int(* | ssh_auth_callback) (const char *prompt, char *buf, size_t len, int echo, int verify, void *userdata)
| SSH authentication callback for password and publickey auth.

## Enumerations
enum | ssh_agent_state_e { SSH_AGENT_STATE_NONE = 0 , SSH_AGENT_STATE_PUBKEY , SSH_AGENT_STATE_CERT , SSH_AGENT_STATE_AUTH }
enum | ssh_auth_auto_state_e { SSH_AUTH_AUTO_STATE_NONE = 0 , SSH_AUTH_AUTO_STATE_PUBKEY , SSH_AUTH_AUTO_STATE_KEY_IMPORTED , SSH_AUTH_AUTO_STATE_CERTIFICATE_FILE , SSH_AUTH_AUTO_STATE_CERTIFICATE_OPTION , SSH_AUTH_AUTO_STATE_PUBKEY_ACCEPTED }

## Functions
int | ssh_set_agent_channel (ssh_session session, ssh_channel channel)
| sets the SSH agent channel. The SSH agent channel will be used to authenticate this client using an agent through a channel, from another session. The most likely use is to implement SSH Agent forwarding into a SSH proxy.
int | ssh_set_agent_socket (ssh_session session, socket_t fd)
| sets the SSH agent socket. The SSH agent will be used to authenticate this client using the given socket to communicate with the ssh-agent. The caller is responsible for connecting to the socket prior to calling this function.
| SSH_PACKET_CALLBACK (ssh_packet_userauth_banner)
| SSH_PACKET_CALLBACK (ssh_packet_userauth_failure)
| SSH_PACKET_CALLBACK (ssh_packet_userauth_success)
| SSH_PACKET_CALLBACK (ssh_packet_userauth_pk_ok)
int | ssh_userauth_list (ssh_session session, const char *username)
| Get available authentication methods from the server.
int | ssh_userauth_none (ssh_session session, const char *username)
| Try to authenticate through the "none" method.
int | ssh_userauth_try_publickey (ssh_session session, const char *username, const ssh_key pubkey)
| Try to authenticate with the given public key.
int | ssh_userauth_publickey (ssh_session session, const char *username, const ssh_key privkey)
| Authenticate with public/private key or certificate.
void | ssh_agent_state_free (void *data)
int | ssh_userauth_agent (ssh_session session, const char *username)
| Try to do public key authentication with ssh agent.
int | ssh_userauth_publickey_auto_get_current_identity (ssh_session session, char **value)
| Get the identity that is currently being processed by ssh_userauth_publickey_auto()
int | ssh_userauth_publickey_auto (ssh_session session, const char *username, const char *passphrase)
| Tries to automatically authenticate with public key and "none".
int | ssh_userauth_password (ssh_session session, const char *username, const char *password)
| Try to authenticate by password.
int | ssh_userauth_agent_pubkey (ssh_session session, const char *username, ssh_public_key publickey)
ssh_kbdint | ssh_kbdint_new (void)
void | ssh_kbdint_free (ssh_kbdint kbd)
void | ssh_kbdint_clean (ssh_kbdint kbd)
| SSH_PACKET_CALLBACK (ssh_packet_userauth_info_request)
int | ssh_userauth_kbdint (ssh_session session, const char *user, const char *submethods)
| Try to authenticate through the "keyboard-interactive" method.
int | ssh_userauth_kbdint_getnprompts (ssh_session session)
| Get the number of prompts (questions) the server has given.
const char * | ssh_userauth_kbdint_getname (ssh_session session)
| Get the "name" of the message block.
const char * | ssh_userauth_kbdint_getinstruction (ssh_session session)
| Get the "instruction" of the message block.
const char * | ssh_userauth_kbdint_getprompt (ssh_session session, unsigned int i, char *echo)
| Get a prompt from a message block.
int | ssh_userauth_kbdint_getnanswers (ssh_session session)
| Get the number of answers the client has given.
const char * | ssh_userauth_kbdint_getanswer (ssh_session session, unsigned int i)
| Get the answer to a question from a message block.
int | ssh_userauth_kbdint_setanswer (ssh_session session, unsigned int i, const char *answer)
| Set the answer for a question from a message block.
int | ssh_userauth_gssapi (ssh_session session)
| Try to authenticate through the "gssapi-with-mic" method.

## Detailed Description

Functions to authenticate with a server.

## Typedef Documentation

## ◆ ssh_auth_callback

typedef int(* ssh_auth_callback) (const char *prompt, char *buf, size_t len, int echo, int verify, void *userdata)

SSH authentication callback for password and publickey auth.

Parameters

  prompt | Prompt to be displayed.
  buf | Buffer to save the password. You should null-terminate it.
  len | Length of the buffer.
  echo | Enable or disable the echo of what you type.
  verify | Should the password be verified?
  userdata | Userdata to be passed to the callback function. Useful for GUI applications.

Returns
  0 on success, < 0 on error.

## Function Documentation

## ◆ ssh_set_agent_channel()

int ssh_set_agent_channel | ( | ssh_session | session,
|  | ssh_channel | channel )

sets the SSH agent channel. The SSH agent channel will be used to authenticate this client using an agent through a channel, from another session. The most likely use is to implement SSH Agent forwarding into a SSH proxy.

Parameters

  | session | the session
  [in] | channel | a SSH channel from another session.

Returns
  SSH_OK in case of success SSH_ERROR in case of an error

## ◆ ssh_set_agent_socket()

int ssh_set_agent_socket | ( | ssh_session | session,
|  | socket_t | fd )

sets the SSH agent socket. The SSH agent will be used to authenticate this client using the given socket to communicate with the ssh-agent. The caller is responsible for connecting to the socket prior to calling this function.

Returns
  SSH_OK in case of success SSH_ERROR in case of an error

## ◆ ssh_userauth_agent()

int ssh_userauth_agent | ( | ssh_session | session,
|  | const char * | username )

Try to do public key authentication with ssh agent.

Parameters

  [in] | session | The ssh session to use.
  [in] | username | The username, this SHOULD be NULL.

Returns
  SSH_AUTH_ERROR: A serious error happened.
  SSH_AUTH_DENIED: The server doesn't accept that public key as an authentication token. Try another key or another method.
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method.
  SSH_AUTH_SUCCESS: The public key is accepted, you want now to use ssh_userauth_publickey().
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

Note
  Most server implementations do not permit changing the username during authentication. The username should only be set with ssh_options_set() only before you connect to the server.

## ◆ ssh_userauth_gssapi()

int ssh_userauth_gssapi | ( | ssh_session | session | ) |

Try to authenticate through the "gssapi-with-mic" method.

Parameters

  [in] | session | The ssh session to use.

Returns
  SSH_AUTH_ERROR: A serious error happened
  SSH_AUTH_DENIED: Authentication failed : use another method
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method
  SSH_AUTH_SUCCESS: Authentication success
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

## ◆ ssh_userauth_kbdint()

int ssh_userauth_kbdint | ( | ssh_session | session,
|  | const char * | user,
|  | const char * | submethods )

Try to authenticate through the "keyboard-interactive" method.

Parameters

  [in] | session | The ssh session to use.
  [in] | user | The username to authenticate. You can specify NULL if ssh_option_set_username() has been used. You cannot try two different logins in a row.
  [in] | submethods | Undocumented. Set it to NULL.

Returns
  SSH_AUTH_ERROR: A serious error happened
  SSH_AUTH_DENIED: Authentication failed : use another method
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method
  SSH_AUTH_SUCCESS: Authentication success
  SSH_AUTH_INFO: The server asked some questions. Use ssh_userauth_kbdint_getnprompts() and such.
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

See also
  ssh_userauth_kbdint_getnprompts()
  ssh_userauth_kbdint_getname()
  ssh_userauth_kbdint_getinstruction()
  ssh_userauth_kbdint_getprompt()
  ssh_userauth_kbdint_setanswer()

## ◆ ssh_userauth_kbdint_getanswer()

const char * ssh_userauth_kbdint_getanswer | ( | ssh_session | session,
|  | unsigned int | i )

Get the answer to a question from a message block.

Parameters

  [in] | session | The ssh session to use.
  [in] | i | index The number of the ith answer.

Returns
  The answer string, or NULL if the answer is not available. Do not free the string.

## ◆ ssh_userauth_kbdint_getinstruction()

const char * ssh_userauth_kbdint_getinstruction | ( | ssh_session | session | ) |

Get the "instruction" of the message block.

Once you have called ssh_userauth_kbdint() and received SSH_AUTH_INFO return code, this function can be used to retrieve information about the keyboard interactive authentication questions sent by the remote host.

Parameters

  [in] | session | The ssh session to use.

Returns
  The instruction of the message block.

## ◆ ssh_userauth_kbdint_getname()

const char * ssh_userauth_kbdint_getname | ( | ssh_session | session | ) |

Get the "name" of the message block.

Once you have called ssh_userauth_kbdint() and received SSH_AUTH_INFO return code, this function can be used to retrieve information about the keyboard interactive authentication questions sent by the remote host.

Parameters

  [in] | session | The ssh session to use.

Returns
  The name of the message block. Do not free it.

## ◆ ssh_userauth_kbdint_getnanswers()

int ssh_userauth_kbdint_getnanswers | ( | ssh_session | session | ) |

Get the number of answers the client has given.

Parameters

  [in] | session | The ssh session to use.

Returns
  The number of answers.

## ◆ ssh_userauth_kbdint_getnprompts()

int ssh_userauth_kbdint_getnprompts | ( | ssh_session | session | ) |

Get the number of prompts (questions) the server has given.

Once you have called ssh_userauth_kbdint() and received SSH_AUTH_INFO return code, this function can be used to retrieve information about the keyboard interactive authentication questions sent by the remote host.

Parameters

  [in] | session | The ssh session to use.

Returns
  The number of prompts.

## ◆ ssh_userauth_kbdint_getprompt()

const char * ssh_userauth_kbdint_getprompt | ( | ssh_session | session,
|  | unsigned int | i,
|  | char * | echo )

Get a prompt from a message block.

Once you have called ssh_userauth_kbdint() and received SSH_AUTH_INFO return code, this function can be used to retrieve information about the keyboard interactive authentication questions sent by the remote host.

Parameters

  [in] | session | The ssh session to use.
  [in] | i | The index number of the i'th prompt.
  [out] | echo | This is an optional variable. You can obtain a boolean if the user input should be echoed or hidden. For passwords it is usually hidden.

Returns
  A pointer to the prompt. Do not free it.

const char prompt;
char echo;
prompt = ssh_userauth_kbdint_getprompt(session, 0, &echo);
if (echo) ...
ssh_userauth_kbdint_getprompt
LIBSSH_API const char * ssh_userauth_kbdint_getprompt(ssh_session session, unsigned int i, char *echo)
Get a prompt from a message block.
Definition auth.c:2187

## ◆ ssh_userauth_kbdint_setanswer()

int ssh_userauth_kbdint_setanswer | ( | ssh_session | session,
|  | unsigned int | i,
|  | const char * | answer )

Set the answer for a question from a message block.

If you have called ssh_userauth_kbdint() and got SSH_AUTH_INFO, this function returns the questions from the server.

Parameters

  [in] | session | The ssh session to use.
  [in] | i | index The number of the ith prompt.
  [in] | answer | The answer to give to the server. The answer MUST be encoded UTF-8. It is up to the server how to interpret the value and validate it. However, if you read the answer in some other encoding, you MUST convert it to UTF-8.

Returns
  0 on success, < 0 on error.

## ◆ ssh_userauth_list()

int ssh_userauth_list | ( | ssh_session | session,
|  | const char * | username )

Get available authentication methods from the server.

This requires the function ssh_userauth_none() to be called before the methods are available. The server MAY return a list of methods that may continue.

Parameters

  [in] | session | The SSH session.
  [in] | username | Deprecated, set to NULL.

Returns
  A bitfield of the following values:
  - SSH_AUTH_METHOD_PASSWORD
  - SSH_AUTH_METHOD_PUBLICKEY
  - SSH_AUTH_METHOD_HOSTBASED
  - SSH_AUTH_METHOD_INTERACTIVE

Warning
  Other reserved flags may appear in future versions.

See also
  ssh_userauth_none()

## ◆ ssh_userauth_none()

int ssh_userauth_none | ( | ssh_session | session,
|  | const char * | username )

Try to authenticate through the "none" method.

Parameters

  [in] | session | The ssh session to use.
  [in] | username | The username, this SHOULD be NULL.

Returns
  SSH_AUTH_ERROR: A serious error happened.
  SSH_AUTH_DENIED: Authentication failed: use another method
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method
  SSH_AUTH_SUCCESS: Authentication success
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

Note
  Most server implementations do not permit changing the username during authentication. The username should only be set with ssh_options_set() only before you connect to the server.

## ◆ ssh_userauth_password()

int ssh_userauth_password | ( | ssh_session | session,
|  | const char * | username,
|  | const char * | password )

Try to authenticate by password.

This authentication method is normally disabled on SSHv2 server. You should use keyboard-interactive mode.

The 'password' value MUST be encoded UTF-8. It is up to the server how to interpret the password and validate it against the password database. However, if you read the password in some other encoding, you MUST convert the password to UTF-8.

Parameters

  [in] | session | The ssh session to use.
  [in] | username | The username, this SHOULD be NULL.
  [in] | password | The password to authenticate in UTF-8.

Returns
  SSH_AUTH_ERROR: A serious error happened.
  SSH_AUTH_DENIED: Authentication failed: use another method
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method
  SSH_AUTH_SUCCESS: Authentication success
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

Note
  Most server implementations do not permit changing the username during authentication. The username should only be set with ssh_options_set() only before you connect to the server.

See also
  ssh_userauth_none()
  ssh_userauth_kbdint()

## ◆ ssh_userauth_publickey()

int ssh_userauth_publickey | ( | ssh_session | session,
|  | const char * | username,
|  | const ssh_key | privkey )

Authenticate with public/private key or certificate.

Parameters

  [in] | session | The SSH session.
  [in] | username | The username, this SHOULD be NULL.
  [in] | privkey | The private key for authentication.

Returns
  SSH_AUTH_ERROR: A serious error happened.
  SSH_AUTH_DENIED: The server doesn't accept that public key as an authentication token. Try another key or another method.
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method.
  SSH_AUTH_SUCCESS: The public key is accepted.
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

Note
  Most server implementations do not permit changing the username during authentication. The username should only be set with ssh_options_set() only before you connect to the server.

## ◆ ssh_userauth_publickey_auto()

int ssh_userauth_publickey_auto | ( | ssh_session | session,
|  | const char * | username,
|  | const char * | passphrase )

Tries to automatically authenticate with public key and "none".

It may fail, for instance it doesn't ask for a password and uses a default asker for passphrases (in case the private key is encrypted).

Parameters

  [in] | session | The SSH session.
  [in] | username | The username, this SHOULD be NULL.
  [in] | passphrase | Use this passphrase to unlock the privatekey. Use NULL if you don't want to use a passphrase or the user should be asked.

Returns
  SSH_AUTH_ERROR: A serious error happened.
  SSH_AUTH_DENIED: The server doesn't accept that public key as an authentication token. Try another key or another method.
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method.
  SSH_AUTH_SUCCESS: Authentication success
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

Note
  Most server implementations do not permit changing the username during authentication. The username should only be set with ssh_options_set() only before you connect to the server.

The OpenSSH iterates over the identities and first try the plain public key and then the certificate if it is in place.

## ◆ ssh_userauth_publickey_auto_get_current_identity()

int ssh_userauth_publickey_auto_get_current_identity | ( | ssh_session | session,
|  | char ** | value )

Get the identity that is currently being processed by ssh_userauth_publickey_auto()

This is meant to be used by a callback that happens as part of the execution of ssh_userauth_publickey_auto(). The auth_function callback might want to know which key a passphrase is needed for, for example.

Parameters

  [in] | session | The SSH session.
  [out] | value | The value to get into. As a char**, space will be allocated by the function for the value, it is your responsibility to free the memory using ssh_string_free_char().

Returns
  SSH_OK on success, SSH_ERROR on error.

## ◆ ssh_userauth_try_publickey()

int ssh_userauth_try_publickey | ( | ssh_session | session,
|  | const char * | username,
|  | const ssh_key | pubkey )

Try to authenticate with the given public key.

To avoid unnecessary processing and user interaction, the following method is provided for querying whether authentication using the 'pubkey' would be possible.

Parameters

  [in] | session | The SSH session.
  [in] | username | The username, this SHOULD be NULL.
  [in] | pubkey | The public key to try.

Returns
  SSH_AUTH_ERROR: A serious error happened.
  SSH_AUTH_DENIED: The server doesn't accept that public key as an authentication token. Try another key or another method.
  SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method.
  SSH_AUTH_SUCCESS: The public key is accepted, you want now to use ssh_userauth_publickey().
  SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

Note
  Most server implementations do not permit changing the username during authentication. The username should only be set with ssh_options_set() only before you connect to the server.