Functions to authenticate with a server. More...

Functions
int	ssh_userauth_agent (ssh_session session, const char *username)
	Try to do public key authentication with ssh agent. More...

int	ssh_userauth_gssapi (ssh_session session)
	Try to authenticate through the "gssapi-with-mic" method. More...

int	ssh_userauth_kbdint (ssh_session session, const char user, const char submethods)
	Try to authenticate through the "keyboard-interactive" method. More...

const char *	ssh_userauth_kbdint_getanswer (ssh_session session, unsigned int i)
	Get the answer for a question from a message block. More...

const char *	ssh_userauth_kbdint_getinstruction (ssh_session session)
	Get the "instruction" of the message block. More...

const char *	ssh_userauth_kbdint_getname (ssh_session session)
	Get the "name" of the message block. More...

int	ssh_userauth_kbdint_getnanswers (ssh_session session)
	Get the number of answers the client has given. More...

int	ssh_userauth_kbdint_getnprompts (ssh_session session)
	Get the number of prompts (questions) the server has given. More...

const char *	ssh_userauth_kbdint_getprompt (ssh_session session, unsigned int i, char *echo)
	Get a prompt from a message block. More...

int	ssh_userauth_kbdint_setanswer (ssh_session session, unsigned int i, const char *answer)
	Set the answer for a question from a message block. More...

int	ssh_userauth_list (ssh_session session, const char *username)
	Get available authentication methods from the server. More...

int	ssh_userauth_none (ssh_session session, const char *username)
	Try to authenticate through the "none" method. More...

int	ssh_userauth_password (ssh_session session, const char username, const char password)
	Try to authenticate by password. More...

int	ssh_userauth_publickey (ssh_session session, const char *username, const ssh_key privkey)
	Authenticate with public/private key. More...

int	ssh_userauth_publickey_auto (ssh_session session, const char username, const char passphrase)
	Tries to automatically authenticate with public key and "none". More...

int	ssh_userauth_try_publickey (ssh_session session, const char *username, const ssh_key pubkey)
	Try to authenticate with the given public key. More...

Detailed Description

Functions to authenticate with a server.

Function Documentation

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_pubkey(). 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.

References ssh_key_free(), ssh_string_free_char(), and ssh_userauth_try_publickey().

Referenced by ssh_userauth_publickey_auto().

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.

References SSH_LOG_PROTOCOL.

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()

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

Get the answer for a question from a message block.

Parameters

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

Returns: 0 on success, < 0 on error.

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.

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.

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.

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.

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) ...

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.

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 fllowing 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()

Referenced by ssh::Session::getAuthList().

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.

Referenced by ssh::Session::userauthNone().

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()

Referenced by ssh::Session::userauthPassword().

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

Authenticate with public/private key.

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, you want now to use ssh_userauth_pubkey(). 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.

References ssh_key_is_private(), and ssh_string_free().

Referenced by ssh_userauth_publickey_auto(), and ssh::Session::userauthPublickey().

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: The public key is accepted, you want now to use ssh_userauth_pubkey(). 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.

References ssh_key_free(), ssh_pki_export_privkey_to_pubkey(), ssh_pki_import_privkey_file(), ssh_pki_import_pubkey_file(), ssh_userauth_agent(), ssh_userauth_publickey(), and ssh_userauth_try_publickey().

Referenced by ssh::Session::userauthPublickeyAuto().

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_pubkey(). 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.

References ssh_key_is_public(), and ssh_string_free().

Referenced by ssh_userauth_agent(), ssh_userauth_publickey_auto(), and ssh::Session::userauthTryPublickey().