libssh  0.5.4
Functions
The SSH authentication functions.

Functions to authenticate with a server. More...

Functions

void privatekey_free (ssh_private_key prv)
 Deallocate a private key object. More...
 
ssh_private_key privatekey_from_file (ssh_session session, const char *filename, int type, const char *passphrase)
 Reads a SSH private key from a file. More...
 
ssh_string publickey_from_file (ssh_session session, const char *filename, int *type)
 Retrieve a public key from a file. More...
 
ssh_public_key publickey_from_privatekey (ssh_private_key prv)
 Make a public_key object out of a private_key object. More...
 
ssh_string publickey_to_string (ssh_public_key key)
 Convert a public_key object into a a SSH string. More...
 
int ssh_auth_list (ssh_session session)
 retrieves available authentication methods for this session More...
 
enum ssh_keytypes_e ssh_privatekey_type (ssh_private_key privatekey)
 returns the type of a private key More...
 
int ssh_publickey_to_file (ssh_session session, const char *file, ssh_string pubkey, int type)
 Write a public key to a file. More...
 
int ssh_try_publickey_from_file (ssh_session session, const char *keyfile, ssh_string *publickey, int *type)
 Try to read the public key from a given file. More...
 
int ssh_userauth_agent_pubkey (ssh_session session, const char *username, ssh_public_key publickey)
 Try to authenticate through public key with an ssh agent. More...
 
int ssh_userauth_autopubkey (ssh_session session, const char *passphrase)
 Tries to automatically authenticate with public key and "none". 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_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_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)
 retrieves available authentication methods for this session More...
 
int ssh_userauth_none (ssh_session session, const char *username)
 Try to authenticate through the "none" method. More...
 
int ssh_userauth_offer_pubkey (ssh_session session, const char *username, int type, ssh_string publickey)
 Try to authenticate through public key. More...
 
int ssh_userauth_password (ssh_session session, const char *username, const char *password)
 Try to authenticate by password. More...
 
int ssh_userauth_privatekey_file (ssh_session session, const char *username, const char *filename, const char *passphrase)
 Try to authenticate through a private key file. More...
 
int ssh_userauth_pubkey (ssh_session session, const char *username, ssh_string publickey, ssh_private_key privatekey)
 Try to authenticate through public key. More...
 

Detailed Description

Functions to authenticate with a server.

Function Documentation

void privatekey_free ( ssh_private_key  prv)

Deallocate a private key object.

Parameters
[in]prvThe private_key object to free.

Referenced by ssh_bind_accept(), ssh_free(), ssh_userauth_autopubkey(), and ssh_userauth_privatekey_file().

ssh_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
[in]sessionThe SSH Session to use.
[in]filenameThe filename of the the private key.
[in]typeThe type of the private key. This could be SSH_KEYTYPE_DSS or SSH_KEYTYPE_RSA. Pass 0 to automatically detect the type.
[in]passphraseThe 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 on error.
See Also
privatekey_free()
publickey_from_privatekey()

References ssh_init(), ssh_log(), and SSH_LOG_RARE.

Referenced by ssh_key_import_private(), ssh_userauth_autopubkey(), and ssh_userauth_privatekey_file().

ssh_string publickey_from_file ( ssh_session  session,
const char *  filename,
int *  type 
)

Retrieve a public key from a file.

Parameters
[in]sessionThe SSH session to use.
[in]filenameThe filename of the public key.
[out]typeThe Pointer to a integer. If it is not NULL, it will contain 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 ssh_buffer_free(), ssh_string_fill(), and ssh_string_new().

Referenced by ssh_try_publickey_from_file(), and ssh_userauth_privatekey_file().

ssh_public_key publickey_from_privatekey ( ssh_private_key  prv)

Make a public_key object out of a private_key object.

Parameters
[in]prvThe private key to generate the public key.
Returns
The generated public key, NULL on error.
See Also
publickey_to_string()

References ssh_string_burn(), ssh_string_data(), ssh_string_fill(), ssh_string_free(), ssh_string_len(), and ssh_string_new().

Referenced by ssh_userauth_autopubkey(), and ssh_userauth_pubkey().

ssh_string publickey_to_string ( ssh_public_key  key)

Convert a public_key object into a a SSH string.

Parameters
[in]keyThe public key to convert.
Returns
An allocated SSH String containing the public key, NULL on error.
See Also
string_free()

References ssh_buffer_free(), ssh_buffer_new(), ssh_string_fill(), ssh_string_free(), ssh_string_from_char(), and ssh_string_new().

Referenced by ssh_userauth_agent_pubkey(), ssh_userauth_autopubkey(), and ssh_userauth_pubkey().

int ssh_auth_list ( ssh_session  session)

retrieves available authentication methods for this session

Deprecated:
See Also
ssh_userauth_list

References ssh_userauth_list().

enum ssh_keytypes_e ssh_privatekey_type ( ssh_private_key  privatekey)

returns the type of a private key

Parameters
[in]privatekeythe private key handle
Returns
one of SSH_KEYTYPE_RSA,SSH_KEYTYPE_DSS,SSH_KEYTYPE_RSA1
SSH_KEYTYPE_UNKNOWN if the type is unknown
See Also
privatekey_from_file
ssh_userauth_offer_pubkey
int ssh_publickey_to_file ( ssh_session  session,
const char *  file,
ssh_string  pubkey,
int  type 
)

Write a public key to a file.

Parameters
[in]sessionThe ssh session to use.
[in]fileThe filename to write the key into.
[in]pubkeyThe public key to write.
[in]typeThe type of the public key.
Returns
0 on success, -1 on error.

References ssh_log(), SSH_LOG_PACKET, SSH_LOG_RARE, and ssh_string_len().

Referenced by ssh_userauth_autopubkey().

int ssh_try_publickey_from_file ( ssh_session  session,
const char *  keyfile,
ssh_string *  publickey,
int *  type 
)

Try to read the public key from a given file.

Parameters
[in]sessionThe ssh session to use.
[in]keyfileThe name of the private keyfile.
[out]publickeyA ssh_string to store the public key.
[out]typeA pointer to an integer to store the type.
Returns
0 on success, -1 on error or the private key doesn't exist, 1 if the public key doesn't exist.

References publickey_from_file(), ssh_get_error(), ssh_log(), and SSH_LOG_PACKET.

Referenced by ssh_userauth_autopubkey().

int ssh_userauth_agent_pubkey ( ssh_session  session,
const char *  username,
ssh_public_key  publickey 
)

Try to authenticate through public key with an ssh agent.

Parameters
[in]sessionThe ssh session to use.
[in]usernameThe 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]publickeyThe 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(), ssh_string_free(), and ssh_string_from_char().

Referenced by ssh_userauth_autopubkey().

int ssh_userauth_autopubkey ( ssh_session  session,
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]sessionThe ssh session to authenticate with.
[in]passphraseUse 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()

References privatekey_free(), privatekey_from_file(), publickey_from_privatekey(), publickey_to_string(), ssh_log(), SSH_LOG_PACKET, SSH_LOG_PROTOCOL, SSH_LOG_RARE, ssh_publickey_to_file(), ssh_string_free(), ssh_try_publickey_from_file(), ssh_userauth_agent_pubkey(), ssh_userauth_none(), ssh_userauth_offer_pubkey(), and ssh_userauth_pubkey().

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

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

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

Parameters
[in]sessionThe ssh session to use.
[in]userThe 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]submethodsUndocumented. 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_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
[in]sessionThe 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
[in]sessionThe 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
[in]sessionThe 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
[in]sessionThe ssh session to use.
[in]iThe index number of the i'th prompt.
[in]echoWhen 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 
)

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]sessionThe ssh session to use.
[in]iindex The number of the ith prompt.
[in]answerThe answer to give to the server.
Returns
0 on success, < 0 on error.
int ssh_userauth_list ( ssh_session  session,
const char *  username 
)

retrieves available authentication methods for this session

Parameters
[in]sessionthe SSH session
[in]usernameDeprecated, set to NULL.
Returns
A bitfield of 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.
This call will block, even in nonblocking mode, if run for the first time before a (complete) call to ssh_userauth_none.

References ssh_userauth_none().

Referenced by ssh::Session::getAuthList(), and ssh_auth_list().

int ssh_userauth_none ( ssh_session  session,
const char *  username 
)

Try to authenticate through the "none" method.

Parameters
[in]sessionThe ssh session to use.
[in]usernameDeprecated, set 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_AGAIN: In nonblocking mode, you've got to call this again later.

References ssh_string_free(), and ssh_string_from_char().

Referenced by ssh_userauth_autopubkey(), ssh_userauth_list(), and ssh::Session::userauthNone().

int ssh_userauth_offer_pubkey ( ssh_session  session,
const char *  username,
int  type,
ssh_string  publickey 
)

Try to authenticate through public key.

Parameters
[in]sessionThe ssh session to use.
[in]usernameThe 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]typeThe type of the public key. This value is given by publickey_from_file() or ssh_privatekey_type().
[in]publickeyA 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_privatekey_type()
ssh_userauth_pubkey()

References ssh_string_free(), and ssh_string_from_char().

Referenced by ssh_userauth_autopubkey(), and ssh::Session::userauthOfferPubkey().

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

Try to authenticate by password.

Parameters
[in]sessionThe ssh session to use.
[in]usernameThe 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]passwordThe 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.
SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.
See Also
ssh_userauth_kbdint()
BURN_STRING

References ssh_string_burn(), ssh_string_free(), and ssh_string_from_char().

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

int ssh_userauth_privatekey_file ( ssh_session  session,
const char *  username,
const char *  filename,
const char *  passphrase 
)

Try to authenticate through a private key file.

Parameters
[in]sessionThe ssh session to use.
[in]usernameThe 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]filenameFilename containing the private key.
[in]passphrasePassphrase to decrypt the private key. Set to null if none is needed or it is unknown.
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.
SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.
See Also
publickey_from_file()
privatekey_from_file()
privatekey_free()
ssh_userauth_pubkey()

References privatekey_free(), privatekey_from_file(), publickey_from_file(), ssh_log(), SSH_LOG_RARE, ssh_string_free(), and ssh_userauth_pubkey().

int ssh_userauth_pubkey ( ssh_session  session,
const char *  username,
ssh_string  publickey,
ssh_private_key  privatekey 
)

Try to authenticate through public key.

Parameters
[in]sessionThe ssh session to use.
[in]usernameThe 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]publickeyA public key returned by publickey_from_file(), or NULL to generate automatically from privatekey.
[in]privatekeyA 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 publickey_from_privatekey(), publickey_to_string(), ssh_string_free(), and ssh_string_from_char().

Referenced by ssh_userauth_autopubkey(), ssh_userauth_privatekey_file(), and ssh::Session::userauthPubkey().