SSH Authentication functions

functions to authenticate to servers More...

Functions
void	privatekey_free (PRIVATE_KEY *prv)
	deallocate a private key
PRIVATE_KEY *	privatekey_from_file (SSH_SESSION *session, const char *filename, int type, const char *passphrase)
	Reads a SSH private key from a file.
STRING *	publickey_from_file (SSH_SESSION *session, const char *filename, int *type)
	Retrieve a public key from a file.
PUBLIC_KEY *	publickey_from_privatekey (PRIVATE_KEY *prv)
	Makes a PUBLIC_KEY object out of a PRIVATE_KEY object.
STRING *	publickey_to_string (PUBLIC_KEY *key)
	makes a SSH String out of a PUBLIC_KEY object
int	ssh_userauth_agent_pubkey (SSH_SESSION *session, const char *username, PUBLIC_KEY *publickey)
	Try to authenticate through public key with an ssh agent.
int	ssh_userauth_autopubkey (SSH_SESSION *session, const char *passphrase)
	Tries to automaticaly authenticate with public key and "none".
int	ssh_userauth_kbdint (SSH_SESSION *session, const char *user, const char *submethods)
	Try to authenticate through the "keyboard-interactive" method.
const char *	ssh_userauth_kbdint_getinstruction (SSH_SESSION *session)
	Get the "instruction" of the message block.
const char *	ssh_userauth_kbdint_getname (SSH_SESSION *session)
	Get the "name" of the message block.
int	ssh_userauth_kbdint_getnprompts (SSH_SESSION *session)
	Get the number of prompts (questions) the server has given.
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_setanswer (SSH_SESSION *session, unsigned int i, const char *answer)
	You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO.
int	ssh_userauth_none (SSH_SESSION *session, const char *username)
	Try to authenticate through the "none" method.
int	ssh_userauth_offer_pubkey (SSH_SESSION *session, const char *username, int type, STRING *publickey)
	Try to authenticate through public key.
int	ssh_userauth_password (SSH_SESSION *session, const char *username, const char *password)
	Try to authenticate by password.
int	ssh_userauth_pubkey (SSH_SESSION *session, const char *username, STRING *publickey, PRIVATE_KEY *privatekey)
	Try to authenticate through public key.

---

Detailed Description

functions to authenticate to servers

---

Function Documentation

void privatekey_free

(

PRIVATE_KEY *

prv

)

deallocate a private key

Parameters:

prv

a PRIVATE_KEY object

Referenced by ssh_bind_accept(), and ssh_userauth_autopubkey().

PRIVATE_KEY* privatekey_from_file	(	SSH_SESSION *	session,
		const char *	filename,
		int	type,
		const char *	passphrase
	)

Reads a SSH private key from a file.

Parameters:

	session	SSH Session
	filename	Filename containing the private key
	type	Type of the private key. One of TYPE_DSS or TYPE_RSA.
	passphrase	Passphrase to decrypt the private key. Set to null if none is needed or it is unknown.

Returns:

a PRIVATE_KEY object containing the private key, or NULL if it failed.

See also:

privatekey_free()

publickey_from_privatekey()

Referenced by ssh_userauth_autopubkey().

STRING* publickey_from_file	(	SSH_SESSION *	session,
		const char *	filename,
		int *	type
	)

Retrieve a public key from a file.

Parameters:

	session	the SSH session
	filename	Filename of the key
	_type	Pointer to a integer. If it is not null, it contains the type of the key after execution.

Returns:

a SSH String containing the public key, or NULL if it failed.

See also:

string_free()

publickey_from_privatekey()

References buffer_free(), buffer_get(), buffer_get_len(), string_fill(), and string_new().

PUBLIC_KEY* publickey_from_privatekey

(

PRIVATE_KEY *

prv

)

Makes a PUBLIC_KEY object out of a PRIVATE_KEY object.

Parameters:

prv

the Private key

Returns:

the public key

See also:

publickey_to_string()

References string_burn(), string_fill(), string_free(), string_len(), and string_new().

STRING* publickey_to_string

(

PUBLIC_KEY *

key

)

makes a SSH String out of a PUBLIC_KEY object

Parameters:

key

the public key

Returns:

a SSH String containing the public key

See also:

string_free()

References buffer_free(), buffer_get(), buffer_get_len(), buffer_new(), string_fill(), string_free(), string_from_char(), and string_new().

Referenced by ssh_userauth_agent_pubkey(), and ssh_userauth_autopubkey().

int ssh_userauth_agent_pubkey	(	SSH_SESSION *	session,
		const char *	username,
		PUBLIC_KEY *	publickey
	)

Try to authenticate through public key with an ssh agent.

Parameters:

	session	The ssh session to use.
	username	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.
	publickey	The public key provided by the agent.

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

See also:

publickey_from_file()

privatekey_from_file()

privatekey_free()

ssh_userauth_offer_pubkey()

References publickey_to_string(), string_free(), and string_from_char().

Referenced by ssh_userauth_autopubkey().

int ssh_userauth_autopubkey	(	SSH_SESSION *	session,
		const char *	passphrase
	)

Tries to automaticaly 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:

	session	The ssh session to authenticate with.
	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: 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

See also:

ssh_userauth_kbdint()

ssh_userauth_password()

ssh_options_set_identity()

References privatekey_free(), privatekey_from_file(), publickey_to_string(), ssh_log(), SSH_LOG_FUNCTIONS, SSH_LOG_PACKET, SSH_LOG_RARE, ssh_userauth_agent_pubkey(), ssh_userauth_none(), ssh_userauth_offer_pubkey(), ssh_userauth_pubkey(), and string_free().

int ssh_userauth_kbdint	(	SSH_SESSION *	session,
		const char *	user,
		const char *	submethods
	)

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

Parameters:

	session	The ssh session to use.
	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.
	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.

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_getinstruction

(

SSH_SESSION *

session

)

Get the "instruction" of the message block.

You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This function returns the questions from the server.

Parameters:

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.

You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This function returns the questions from the server.

Parameters:

session

The ssh session to use.

Returns:

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

int ssh_userauth_kbdint_getnprompts

(

SSH_SESSION *

session

)

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

You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This function returns the questions from the server.

Parameters:

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.

You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This function returns the questions from the server.

Parameters:

	session	The ssh session to use.
	i	The inndex number of the i'th prompt.
	echo	When different of NULL, it will obtain a boolean meaning that the resulting user input should be echoed or not (like passwords).

Returns:

A pointer to the prompt. Do not free it.

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

You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO.

this function returns the questions from the server set the answer for a question from a message block.

Parameters:

	session	ssh session
	i	index number of the ith prompt
	answer	answer to give to server

Returns:

0 on success, < 0 on error.

int ssh_userauth_none	(	SSH_SESSION *	session,
		const char *	username
	)

Try to authenticate through the "none" method.

Parameters:

	session	The ssh session to use.
	username	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.

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

References string_free(), and string_from_char().

Referenced by ssh_userauth_autopubkey().

int ssh_userauth_offer_pubkey	(	SSH_SESSION *	session,
		const char *	username,
		int	type,
		STRING *	publickey
	)

Try to authenticate through public key.

Parameters:

	session	The ssh session to use.
	username	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.
	type	The type of the public key. This value is given by publickey_from_file().
	publickey	A public key returned by publickey_from_file().

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

See also:

publickey_from_file()

privatekey_from_file()

ssh_userauth_pubkey()

References string_free(), and string_from_char().

Referenced by ssh_userauth_autopubkey().

int ssh_userauth_password	(	SSH_SESSION *	session,
		const char *	username,
		const char *	password
	)

Try to authenticate by password.

Parameters:

	session	The ssh session to use.
	username	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.
	password	The password to use. Take care to clean it after the authentication.

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

See also:

ssh_userauth_kbdint()

BURN_STRING

References string_burn(), string_free(), and string_from_char().

int ssh_userauth_pubkey	(	SSH_SESSION *	session,
		const char *	username,
		STRING *	publickey,
		PRIVATE_KEY *	privatekey
	)

Try to authenticate through public key.

Parameters:

	session	The ssh session to use.
	username	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.
	publickey	A public key returned by publickey_from_file().
	privatekey	A private key returned by privatekey_from_file().

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

See also:

publickey_from_file()

privatekey_from_file()

privatekey_free()

ssh_userauth_offer_pubkey()

References string_free(), and string_from_char().

Referenced by ssh_userauth_autopubkey().