assh/assh_userauth_client.h header reference

Description [link]

This header file defines events which are reported to the application when the assh_service_userauth_client service is running. This service module is an implementation of the client side user authentication protocol.

This standard service described in rfc4252 is implemented as a pluggable service module for libassh.

Members [link]

Types [link]

struct assh_event_userauth_client_banner_s
struct assh_event_userauth_client_keyboard_s
struct assh_event_userauth_client_methods_s
struct assh_event_userauth_client_pwchange_s
struct assh_event_userauth_client_sign_s
union assh_event_userauth_client_u
struct assh_event_userauth_client_user_s

Constant [link]

const struct assh_service_s assh_service_userauth_client

Members detail [link]

struct assh_event_userauth_client_banner_s [link]

This struct is declared in assh/assh_userauth_client.h source file, line 165.

This event is reported when the client-side user authentication service is running and a banner message is received.

Field	Description
const struct assh_cbuffer_s text;	The banner text transmitted by the server. (ro)
const struct assh_cbuffer_s lang;	The language tag. (ro)

struct assh_event_userauth_client_keyboard_s [link]

This struct is declared in assh/assh_userauth_client.h source file, line 215.

This event is reported when the keyboard interactive authentication has been selected and the server sent a SSH_MSG_USERAUTH_INFO_REQUEST message.

The prompts array contains count entries which must be used to query the user. The echos field is a bitmap which indicates user entered values that should be displayed.

Pointers and lengths of user entered values must be stored in the responses array. The prompt array may be reused or a pointer to an other array can be provided. In either cases, all entries must be initialized with user provided response buffers. These buffers can be released after calling the assh_event_done function.

Field	Description
const struct assh_cbuffer_s name;	The name transmitted by the server. (ro)
const struct assh_cbuffer_s instruction;	The instructions transmitted by the server. (ro)
const uint32_t echos;	Indicate fields that must be echoed. (ro)
const uint_fast8_t count;	The number of fields. (ro)
union <anonymous> {
const struct assh_cbuffer_s * prompts;	The array of prompt strings. (ro)
struct assh_cbuffer_s * responses;	The array of response strings. (rw)
};

struct assh_event_userauth_client_methods_s [link]

This struct is declared in assh/assh_userauth_client.h source file, line 105.

This event is reported when the client-side user authentication service is running, before every authentication attempt.

The methods field indicates the authentication methods that are accepted by the server. One of these methods must be selected by setting the select field.

The other fields are initially set to zero and have to be updated depending on the retained authentication method:

When the keyboard-interactive method is selected, the keyboard_sub field will be used as submethods fields of the request.
When the publickey method is selected, the keys field is used.
When the password method is selected, the password field is used.
When the hostbased method is selected, the keys, host_name and host_username fields are used.

The keys linked list can be populated by calling either the assh_key_load, asshh_key_load_file or asshh_key_load_filename functions. Multiple keys can be loaded. The assh library will take care of releasing the provided keys. If a public key is provided, the ASSH_EVENT_USERAUTH_CLIENT_SIGN event will be reported. The library will take care of generating the signature when a private key is provided.

This event may be reported multiple times before the authentication is successful. This occurs when a previous authentication attempt has failed or when the server requires multi factor authentication. The partial_success field is set in the later case.

Field	Description
const assh_bool_t partial_success;	Advertises multi-factor authentication. (ro)
const enum assh_userauth_methods_e methods;	Methods accepted by the server. (ro)
enum assh_userauth_methods_e select;	Must be set to the retained method. (rw)
union <anonymous> {
struct assh_cbuffer_s password;	The password credential. (rw)
struct assh_key_s * keys;	The user or host public key credential. (rw)
struct assh_cbuffer_s keyboard_sub;	The keyboard sub-method. (rw)
};
struct assh_cbuffer_s host_name;	The host name. (rw)
struct assh_cbuffer_s host_username;	The host user name.

struct assh_event_userauth_client_pwchange_s [link]

This struct is declared in assh/assh_userauth_client.h source file, line 183.

This event is reported when the client-side user authentication service is running and a password change request message is received.

The password change is skipped if the new_password field is left empty.

Field	Description
const struct assh_cbuffer_s prompt;	The password change prompt string. (ro)
const struct assh_cbuffer_s lang;	The language tag. (ro)
struct assh_cbuffer_s old_password;	The old password must be stored here. (rw)
struct assh_cbuffer_s new_password;	The new password must be stored here. (rw)

struct assh_event_userauth_client_sign_s [link]

This struct is declared in assh/assh_userauth_client.h source file, line 145.

This event is reported when the client-side user authentication service is running and a public key has been provided for public key authentication.

The private key must be used to generate a signature over the provided authentication data. The sign buffer is allocated by the library. Its size must be reduced if the signature doesn't use the entire provided storage.

Field	Description
struct assh_key_s *const pub_key;	The associated public key. (ro)
const struct assh_algo_sign_s *const algo;	The signature algorithm. (ro)
const struct assh_cbuffer_s auth_data;	The data to authenticate. (ro)
struct assh_buffer_s sign;	Used to store the generated signature. (rw)

union assh_event_userauth_client_u [link]

This union is declared in assh/assh_event.h source file, line 139.

This union contains all client side user authentication related event structures.

Field	Description
struct assh_event_userauth_client_user_s user;
struct assh_event_userauth_client_methods_s methods;
struct assh_event_userauth_client_banner_s banner;
struct assh_event_userauth_client_pwchange_s pwchange;
struct assh_event_userauth_client_keyboard_s keyboard;
struct assh_event_userauth_client_sign_s sign;

struct assh_event_userauth_client_user_s [link]

This struct is declared in assh/assh_userauth_client.h source file, line 58.

This event is reported when the client-side user authentication service is running and the service needs to provide a user name to the server.

Field	Description
struct assh_cbuffer_s username;	The user name transmitted to server (rw)

const struct assh_service_s assh_service_userauth_client [link]

This constant is declared in assh/assh_userauth_client.h source file, line 250.

This constant implements the standard client side ssh-userauth service.