libssh: The libssh server API

libssh 0.8.3 The SSH library

Data Structures | Macros | Typedefs | Enumerations | Functions
The libssh server API

## Data Structures
struct | ssh_bind_callbacks_struct
| These are the callbacks exported by the ssh_bind structure. More...

## Macros
#define | SERVERBANNER CLIENTBANNER
#define | SOCKOPT_TYPE_ARG4 int

## Typedefs
typedef struct ssh_bind_struct * | ssh_bind
typedef void(* | ssh_bind_incoming_connection_callback) (ssh_bind sshbind, void *userdata)
| Incoming connection callback. This callback is called when a ssh_bind has a new incoming connection. More...
typedef struct ssh_bind_callbacks_struct * | ssh_bind_callbacks

## Enumerations
enum | ssh_bind_options_e { SSH_BIND_OPTIONS_BINDADDR, SSH_BIND_OPTIONS_BINDPORT, SSH_BIND_OPTIONS_BINDPORT_STR, SSH_BIND_OPTIONS_HOSTKEY, SSH_BIND_OPTIONS_DSAKEY, SSH_BIND_OPTIONS_RSAKEY, SSH_BIND_OPTIONS_BANNER, SSH_BIND_OPTIONS_LOG_VERBOSITY, SSH_BIND_OPTIONS_LOG_VERBOSITY_STR, SSH_BIND_OPTIONS_ECDSAKEY, SSH_BIND_OPTIONS_IMPORT_KEY }

## Functions
LIBSSH_API ssh_bind | ssh_bind_new (void)
| Creates a new SSH server bind. More...
LIBSSH_API int | ssh_bind_options_set (ssh_bind sshbind, enum ssh_bind_options_e type, const void *value)
LIBSSH_API int | ssh_bind_listen (ssh_bind ssh_bind_o)
| Start listening to the socket. More...
LIBSSH_API int | ssh_bind_set_callbacks (ssh_bind sshbind, ssh_bind_callbacks callbacks, void *userdata)
| Set the callback for this bind. More...
LIBSSH_API void | ssh_bind_set_blocking (ssh_bind ssh_bind_o, int blocking)
| Set the session to blocking/nonblocking mode. More...
LIBSSH_API socket_t | ssh_bind_get_fd (ssh_bind ssh_bind_o)
| Recover the file descriptor from the session. More...
LIBSSH_API void | ssh_bind_set_fd (ssh_bind ssh_bind_o, socket_t fd)
| Set the file descriptor for a session. More...
LIBSSH_API void | ssh_bind_fd_toaccept (ssh_bind ssh_bind_o)
| Allow the file descriptor to accept new sessions. More...
LIBSSH_API int | ssh_bind_accept (ssh_bind ssh_bind_o, ssh_session session)
| Accept an incoming ssh connection and initialize the session. More...
LIBSSH_API int | ssh_bind_accept_fd (ssh_bind ssh_bind_o, ssh_session session, socket_t fd)
| Accept an incoming ssh connection on the given file descriptor and initialize the session. More...
LIBSSH_API ssh_gssapi_creds | ssh_gssapi_get_creds (ssh_session session)
LIBSSH_API int | ssh_handle_key_exchange (ssh_session session)
| Handles the key exchange and set up encryption. More...
LIBSSH_API int | ssh_server_init_kex (ssh_session session)
| Initialize the set of key exchange, hostkey, ciphers, MACs, and compression algorithms for the given ssh_session. More...
LIBSSH_API void | ssh_bind_free (ssh_bind ssh_bind_o)
| Free a ssh servers bind. More...
LIBSSH_API void | ssh_set_auth_methods (ssh_session session, int auth_methods)
| Set the acceptable authentication methods to be sent to the client. More...
LIBSSH_API int | ssh_message_reply_default (ssh_message msg)
| Reply with a standard reject message. More...
LIBSSH_API const char * | ssh_message_auth_user (ssh_message msg)
| Get the name of the authenticated user. More...
LIBSSH_API const char * | ssh_message_auth_password (ssh_message msg)
| Get the password of the authenticated user. More...
LIBSSH_API ssh_key | ssh_message_auth_pubkey (ssh_message msg)
| Get the publickey of the authenticated user. More...
LIBSSH_API int | ssh_message_auth_kbdint_is_response (ssh_message msg)
LIBSSH_API enum ssh_publickey_state_e | ssh_message_auth_publickey_state (ssh_message msg)
LIBSSH_API int | ssh_message_auth_reply_success (ssh_message msg, int partial)
LIBSSH_API int | ssh_message_auth_reply_pk_ok (ssh_message msg, ssh_string algo, ssh_string pubkey)
LIBSSH_API int | ssh_message_auth_reply_pk_ok_simple (ssh_message msg)
LIBSSH_API int | ssh_message_auth_set_methods (ssh_message msg, int methods)
LIBSSH_API int | ssh_message_auth_interactive_request (ssh_message msg, const char *name, const char *instruction, unsigned int num_prompts, const char **prompts, char *echo)
LIBSSH_API int | ssh_message_service_reply_success (ssh_message msg)
LIBSSH_API const char * | ssh_message_service_service (ssh_message msg)
LIBSSH_API int | ssh_message_global_request_reply_success (ssh_message msg, uint16_t bound_port)
LIBSSH_API void | ssh_set_message_callback (ssh_session session, int(*ssh_bind_message_callback)(ssh_session session, ssh_message msg, void *data), void *data)
| defines the ssh_message callback More...
LIBSSH_API int | ssh_execute_message_callbacks (ssh_session session)
LIBSSH_API const char * | ssh_message_channel_request_open_originator (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_open_originator_port (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_open_destination (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_open_destination_port (ssh_message msg)
LIBSSH_API ssh_channel | ssh_message_channel_request_channel (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_pty_term (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_pty_width (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_pty_height (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_pty_pxwidth (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_pty_pxheight (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_env_name (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_env_value (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_command (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_subsystem (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_x11_single_connection (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_x11_auth_protocol (ssh_message msg)
LIBSSH_API const char * | ssh_message_channel_request_x11_auth_cookie (ssh_message msg)
LIBSSH_API int | ssh_message_channel_request_x11_screen_number (ssh_message msg)
LIBSSH_API const char * | ssh_message_global_request_address (ssh_message msg)
LIBSSH_API int | ssh_message_global_request_port (ssh_message msg)
LIBSSH_API int | ssh_channel_open_reverse_forward (ssh_channel channel, const char *remotehost, int remoteport, const char *sourcehost, int localport)
LIBSSH_API int | ssh_channel_open_x11 (ssh_channel channel, const char *orig_addr, int orig_port)
LIBSSH_API int | ssh_channel_request_send_exit_status (ssh_channel channel, int exit_status)
LIBSSH_API int | ssh_channel_request_send_exit_signal (ssh_channel channel, const char *signum, int core, const char *errmsg, const char *lang)
LIBSSH_API int | ssh_send_keepalive (ssh_session session)
SSH_DEPRECATED LIBSSH_API int | ssh_accept (ssh_session session)
SSH_DEPRECATED LIBSSH_API int | channel_write_stderr (ssh_channel channel, const void *data, uint32_t len)
ssh_poll_handle | ssh_bind_get_poll (ssh_bind sshbind)
| SSH_PACKET_CALLBACK (ssh_packet_kexdh_init)
int | ssh_get_key_params (ssh_session session, ssh_key *privkey)
int | ssh_auth_reply_default (ssh_session session, int partial)
ssh_public_key | ssh_message_auth_publickey (ssh_message msg)
int | ssh_auth_reply_success (ssh_session session, int partial)

## Detailed Description

## Typedef Documentation

## ◆ ssh_bind_incoming_connection_callback

typedef void(* ssh_bind_incoming_connection_callback) (ssh_bind sshbind, void *userdata)

Incoming connection callback. This callback is called when a ssh_bind has a new incoming connection.

Parameters

  sshbind | Current sshbind session handler
  userdata | Userdata to be passed to the callback function.

## Function Documentation

## ◆ ssh_bind_accept()

int ssh_bind_accept | ( | ssh_bind | ssh_bind_o,
|  | ssh_session | session
| ) |  |

Accept an incoming ssh connection and initialize the session.

Parameters

  ssh_bind_o | The ssh server bind to accept a connection.
  session | A preallocated ssh session

See also
  ssh_new

Returns
  SSH_OK when a connection is established

## ◆ ssh_bind_accept_fd()

int ssh_bind_accept_fd | ( | ssh_bind | ssh_bind_o,
|  | ssh_session | session,
|  | socket_t | fd
| ) |  |

Accept an incoming ssh connection on the given file descriptor and initialize the session.

Parameters

  ssh_bind_o | The ssh server bind to accept a connection.
  session | A preallocated ssh session
  fd | A file descriptor of an already established TCP inbound connection

See also
  ssh_new
  ssh_bind_accept

Returns
  SSH_OK when a connection is established

## ◆ ssh_bind_fd_toaccept()

void ssh_bind_fd_toaccept | ( | ssh_bind | ssh_bind_o | ) |

Allow the file descriptor to accept new sessions.

Parameters

  ssh_bind_o | The ssh server bind to use.

## ◆ ssh_bind_free()

void ssh_bind_free | ( | ssh_bind | ssh_bind_o | ) |

Free a ssh servers bind.

Parameters

  ssh_bind_o | The ssh server bind to free.

## ◆ ssh_bind_get_fd()

socket_t ssh_bind_get_fd | ( | ssh_bind | ssh_bind_o | ) |

Recover the file descriptor from the session.

Parameters

  ssh_bind_o | The ssh server bind to get the fd from.

Returns
  The file descriptor.

## ◆ ssh_bind_listen()

int ssh_bind_listen | ( | ssh_bind | ssh_bind_o | ) |

Start listening to the socket.

Parameters

  ssh_bind_o | The ssh server bind to use.

Returns
  0 on success, < 0 on error.

## ◆ ssh_bind_new()

ssh_bind ssh_bind_new | ( | void |  | ) |

Creates a new SSH server bind.

Returns
  A newly allocated ssh_bind session pointer.

## ◆ ssh_bind_set_blocking()

void ssh_bind_set_blocking | ( | ssh_bind | ssh_bind_o,
|  | int | blocking
| ) |  |

Set the session to blocking/nonblocking mode.

Parameters

  ssh_bind_o | The ssh server bind to use.
  blocking | Zero for nonblocking mode.

## ◆ ssh_bind_set_callbacks()

int ssh_bind_set_callbacks | ( | ssh_bind | sshbind,
|  | ssh_bind_callbacks | callbacks,
|  | void * | userdata
| ) |  |

Set the callback for this bind.

Parameters

  [in] | sshbind | The bind to set the callback on.
  [in] | callbacks | An already set up ssh_bind_callbacks instance.
  [in] | userdata | A pointer to private data to pass to the callbacks.

Returns
  SSH_OK on success, SSH_ERROR if an error occured.

struct ssh_callbacks_struct cb = {
.userdata = data,
.auth_function = my_auth_function
};
ssh_callbacks_init(&cb);
ssh_bind_set_callbacks(session, &cb);

## ◆ ssh_bind_set_fd()

void ssh_bind_set_fd | ( | ssh_bind | ssh_bind_o,
|  | socket_t | fd
| ) |  |

Set the file descriptor for a session.

Parameters

  ssh_bind_o | The ssh server bind to set the fd.
  fd | The file descriptssh_bind B

## ◆ ssh_handle_key_exchange()

int ssh_handle_key_exchange | ( | ssh_session | session | ) |

Handles the key exchange and set up encryption.

Parameters

  session | A connected ssh session

See also
  ssh_bind_accept

Returns
  SSH_OK if the key exchange was successful

## ◆ ssh_message_auth_password()

const char * ssh_message_auth_password | ( | ssh_message | msg | ) |

Get the password of the authenticated user.

Parameters

  [in] | msg | The message to get the password from.

Returns
  The username or NULL if an error occured.

See also
  ssh_message_get()
  ssh_message_type()

## ◆ ssh_message_auth_pubkey()

ssh_key ssh_message_auth_pubkey | ( | ssh_message | msg | ) |

Get the publickey of the authenticated user.

If you need the key for later user you should duplicate it.

Parameters

  [in] | msg | The message to get the public key from.

Returns
  The public key or NULL.

See also
  ssh_key_dup()
  ssh_key_cmp()
  ssh_message_get()
  ssh_message_type()

## ◆ ssh_message_auth_user()

const char * ssh_message_auth_user | ( | ssh_message | msg | ) |

Get the name of the authenticated user.

Parameters

  [in] | msg | The message to get the username from.

Returns
  The username or NULL if an error occured.

See also
  ssh_message_get()
  ssh_message_type()

## ◆ ssh_message_reply_default()

int ssh_message_reply_default | ( | ssh_message | msg | ) |

Reply with a standard reject message.

Use this function if you don't know what to respond or if you want to reject a request.

Parameters

  [in] | msg | The message to use for the reply.

Returns
  0 on success, -1 on error.

See also
  ssh_message_get()

## ◆ ssh_server_init_kex()

int ssh_server_init_kex | ( | ssh_session | session | ) |

Initialize the set of key exchange, hostkey, ciphers, MACs, and compression algorithms for the given ssh_session.

The selection of algorithms and keys used are determined by the options that are currently set in the given ssh_session structure. May only be called before the initial key exchange has begun.

Parameters

  session | The session structure to initialize.

See also
  ssh_handle_key_exchange
  ssh_options_set

Returns
  SSH_OK if initialization succeeds.

## ◆ ssh_set_auth_methods()

void ssh_set_auth_methods | ( | ssh_session | session,
|  | int | auth_methods
| ) |  |

Set the acceptable authentication methods to be sent to the client.

Parameters

  [in] | session | The server session
  [in] | auth_methods | The authentication methods we will support, which can be bitwise-or'd.

Supported methods are:

SSH_AUTH_METHOD_PASSWORD SSH_AUTH_METHOD_PUBLICKEY SSH_AUTH_METHOD_HOSTBASED SSH_AUTH_METHOD_INTERACTIVE SSH_AUTH_METHOD_GSSAPI_MIC

## ◆ ssh_set_message_callback()

void ssh_set_message_callback | ( | ssh_session | session,
|  | int(*)(ssh_session session, ssh_message msg, void *data) | ssh_bind_message_callback,
|  | void * | data
| ) |  |

defines the ssh_message callback

Parameters

  | session | the current ssh session
  [in] | ssh_bind_message_callback | a function pointer to a callback taking the current ssh session and received message as parameters. the function returns 0 if the message has been parsed and treated successfully, 1 otherwise (libssh must take care of the response).
  [in] | data | void pointer to be passed to callback functions