libssh: The SSH helper functions

libssh 0.12.2 The SSH library

Loading...
Searching...
No Matches
Functions
The SSH helper functions
The libssh API

## Functions
int | ssh_getpass (const char *prompt, char *buf, size_t len, int echo, int verify)
| Get a password from the console.
int | ssh_get_random (void *where, int len, int strong)
| Get random bytes.
int | ssh_file_readaccess_ok (const char *file)
int | ssh_dir_writeable (const char *path)
| Check if the given path is an existing directory and that is accessible for writing.
char * | ssh_get_local_username (void)
int | ssh_is_ipaddr_v4 (const char *str)
int | ssh_is_ipaddr (const char *str)
char * | ssh_get_user_home_dir (ssh_session session)
char * | ssh_lowercase (const char *str)
char * | ssh_hostport (const char *host, int port)
char * | ssh_get_hexa (const unsigned char *what, size_t len)
| Convert a buffer into a colon separated hex string. The caller has to free the memory.
void | ssh_print_hexa (const char *descr, const unsigned char *what, size_t len)
void | ssh_log_hexdump (const char *descr, const unsigned char *what, size_t len)
| Log the content of a buffer in hexadecimal format, similar to the output of 'hexdump -C' command.
const char * | ssh_version (int req_version)
| Check if libssh is the required version or get the version string.
struct ssh_list * | ssh_list_new (void)
void | ssh_list_free (struct ssh_list *list)
struct ssh_iterator * | ssh_list_get_iterator (const struct ssh_list *list)
struct ssh_iterator * | ssh_list_find (const struct ssh_list *list, void *value)
size_t | ssh_list_count (const struct ssh_list *list)
| Get the number of elements in the list.
int | ssh_list_append (struct ssh_list *list, const void *data)
int | ssh_list_prepend (struct ssh_list *list, const void *data)
void | ssh_list_remove (struct ssh_list *list, struct ssh_iterator *iterator)
const void * | _ssh_list_pop_head (struct ssh_list *list)
char * | ssh_dirname (const char *path)
| Parse directory component.
char * | ssh_basename (const char *path)
| basename - parse filename component.
int | ssh_mkdir (const char *pathname, mode_t mode)
| Attempts to create a directory with the given pathname.
int | ssh_mkdirs (const char *pathname, mode_t mode)
| Attempts to create a directory with the given pathname. The missing directories in the given pathname are created recursively.
char * | ssh_path_expand_tilde (const char *d)
| Expand a directory starting with a tilde '~'.
char * | ssh_get_local_hostname (void)
char * | ssh_path_expand_escape (ssh_session session, const char *s)
int | ssh_analyze_banner (ssh_session session, int server)
void | ssh_timestamp_init (struct ssh_timestamp *ts)
int | ssh_make_milliseconds (unsigned long sec, unsigned long usec)
int | ssh_timeout_elapsed (struct ssh_timestamp *ts, int timeout)
int | ssh_timeout_update (struct ssh_timestamp *ts, int timeout)
| updates a timeout value so it reflects the remaining time
void | burn_free (void *ptr, size_t len)
| Securely free memory by overwriting it before deallocation.
char * | strndup (const char *s, size_t n)
void | uint64_inc (unsigned char *counter)
int | ssh_quote_file_name (const char *file_name, char *buf, size_t buf_len)
int | ssh_newline_vis (const char *string, char *buf, size_t buf_len)
int | ssh_tmpname (char *name)
char * | ssh_strreplace (const char *src, const char *pattern, const char *replace)
char * | ssh_strerror (int err_num, char *buf, size_t buflen)
ssize_t | ssh_readn (int fd, void *buf, size_t nbytes)
| Read the requested number of bytes from a local file.
ssize_t | ssh_writen (int fd, const void *buf, size_t nbytes)
| Write the requested number of bytes to a local file.
int | ssh_check_hostname_syntax (const char *hostname)
| Checks syntax of a domain name.
int | ssh_check_username_syntax (const char *username)
| Checks syntax of a username.
void | ssh_proxyjumps_free (struct ssh_list *proxy_jump_list)
| Free proxy jump list.
bool | ssh_libssh_proxy_jumps (void)
| Check if libssh proxy jumps is enabled.
FILE * | ssh_strict_fopen (const char *filename, size_t max_file_size)
int | encode_current_tty_opts (unsigned char *buf, size_t buflen)
| Encode the current TTY options as SSH modes.

## Detailed Description

Different helper functions used in the SSH Library.

## Function Documentation

## ◆ burn_free()

void burn_free | ( | void * | ptr,
|  | size_t | len )

Securely free memory by overwriting it before deallocation.

Overwrites the memory region with zeros before calling free() to prevent sensitive data from remaining in memory after deallocation.

Parameters

  [in] | ptr | Pointer to the memory region to securely free. Can be NULL (no operation performed).
  [in] | len | Length of the memory region in bytes.

## ◆ encode_current_tty_opts()

int encode_current_tty_opts | ( | unsigned char * | buf,
|  | size_t | buflen )

Encode the current TTY options as SSH modes.

Call this function to determine the settings of the process' TTY and encode them as SSH Terminal Modes according to RFC 4254 section 8.

If STDIN isn't connected to a TTY, this function fills the buffer with "sane" default modes.

The encoded modes can be passed to `ssh_channel_request_pty_size_modes` .

unsigned char modes_buf[SSH_TTY_MODES_MAX_BUFSIZE];
encode_current_tty_opts(modes_buf, sizeof(modes_buf));
encode_current_tty_opts
int encode_current_tty_opts(unsigned char *buf, size_t buflen)
Encode the current TTY options as SSH modes.
Definition ttyopts.c:458

Parameters

  [out] | buf | Modes will be encoded into this buffer.
  [in] | buflen | The length of the buffer.

Returns
  number of bytes in the buffer on success, -1 on error.

## ◆ ssh_basename()

char * ssh_basename | ( | const char * | path | ) |

basename - parse filename component.

basename breaks a null-terminated pathname string into a filename component. ssh_basename() returns the component following the final '/'. Trailing '/' characters are not counted as part of the pathname.

Parameters

  [in] | path | The path to parse.

Returns
  The filename of path or NULL if we can't allocate memory. If path is the string "/", basename returns the string "/". If path is NULL or an empty string, "." is returned. The caller needs to free this memory ssh_string_free_char().

See also
  ssh_string_free_char()

## ◆ ssh_check_hostname_syntax()

int ssh_check_hostname_syntax | ( | const char * | hostname | ) |

Checks syntax of a domain name.

The check is made based on the RFC1035 section 2.3.1 Allowed characters are: hyphen, period, digits (0-9) and letters (a-zA-Z)

The label should be no longer than 63 characters The label should start with a letter and end with a letter or number The label in this implementation can start with a number to allow virtual URLs to pass. Note that this will make IPv4 addresses to pass this check too.

Parameters

  hostname | The domain name to be checked, has to be null terminated

Returns
  SSH_OK if the hostname passes syntax check SSH_ERROR otherwise or if hostname is NULL or empty string

## ◆ ssh_check_username_syntax()

int ssh_check_username_syntax | ( | const char * | username | ) |

Checks syntax of a username.

This check disallows metacharacters in the username

Parameters

  username | The username to be checked, has to be null terminated

Returns
  SSH_OK if the username passes syntax check SSH_ERROR otherwise or if username is NULL or empty string

## ◆ ssh_dir_writeable()

int ssh_dir_writeable | ( | const char * | path | ) |

Check if the given path is an existing directory and that is accessible for writing.

Parameters

  [in] | path | Path to the directory to be checked

Returns
  Return 1 if the directory exists and is accessible; 0 otherwise

## ◆ ssh_dirname()

char * ssh_dirname | ( | const char * | path | ) |

Parse directory component.

dirname breaks a null-terminated pathname string into a directory component. In the usual case, ssh_dirname() returns the string up to, but not including, the final '/'. Trailing '/' characters are not counted as part of the pathname. The caller must free the memory using ssh_string_free_char().

Parameters

  [in] | path | The path to parse.

Returns
  The dirname of path or NULL if we can't allocate memory. If path does not contain a slash, c_dirname() returns the string ".". If path is a string "/", it returns the string "/". If path is NULL or an empty string, "." is returned. The memory needs to be freed using ssh_string_free_char().

See also
  ssh_string_free_char()

## ◆ ssh_get_hexa()

char * ssh_get_hexa | ( | const unsigned char * | what,
|  | size_t | len )

Convert a buffer into a colon separated hex string. The caller has to free the memory.

Parameters

  [in] | what | What should be converted to a hex string.
  [in] | len | Length of the buffer to convert.

Returns
  The hex string or NULL on error. The memory needs to be freed using ssh_string_free_char().

See also
  ssh_string_free_char()

## ◆ ssh_get_random()

int ssh_get_random | ( | void * | where,
|  | int | len,
|  | int | strong )

Get random bytes.

Make sure to always check the return code of this function!

Parameters

  [in] | where | The buffer to fill with random bytes
  [in] | len | The size of the buffer to fill.
  [in] | strong | Use a strong or private RNG source.

Returns
  1 on success, 0 on error.

## ◆ ssh_getpass()

int ssh_getpass | ( | const char * | prompt,
|  | char * | buf,
|  | size_t | len,
|  | int | echo,
|  | int | verify )

Get a password from the console.

You should make sure that the buffer is an empty string!

You can also use this function to ask for a username. Then you can fill the buffer with the username and it is shows to the users. If the users just presses enter the buffer will be untouched.

char username[128];
snprintf(username, sizeof(username), "john");
ssh_getpass("Username:", username, sizeof(username), 1, 0);
ssh_getpass
LIBSSH_API int ssh_getpass(const char *prompt, char *buf, size_t len, int echo, int verify)
Get a password from the console.
Definition getpass.c:214

The prompt will look like this:

Username: [john]

If you press enter then john is used as the username, or you can type it in to change it.

Parameters

  [in] | prompt | The prompt to show to ask for the password.
  [out] | buf | The buffer the password should be stored. It NEEDS to be empty or filled out.
  [in] | len | The length of the buffer.
  [in] | echo | Should we echo what you type.
  [in] | verify | Should we ask for the password twice.

Returns
  0 on success, -1 on error.

## ◆ ssh_libssh_proxy_jumps()

bool ssh_libssh_proxy_jumps | ( | void |  | ) |

Check if libssh proxy jumps is enabled.

If env variable OPENSSH_PROXYJUMP is set to 1 then proxyjump will be through the OpenSSH binary.

Returns
  false if OPENSSH_PROXYJUMP=1 true otherwise

## ◆ ssh_list_count()

size_t ssh_list_count | ( | const struct ssh_list * | list | ) |

Get the number of elements in the list.

Parameters

  [in] | list | The list to count.

Returns
  The number of elements in the list.

## ◆ ssh_log_hexdump()

void ssh_log_hexdump | ( | const char * | descr,
|  | const unsigned char * | what,
|  | size_t | len )

Log the content of a buffer in hexadecimal format, similar to the output of 'hexdump -C' command.

The first logged line is the given description followed by the length. Then the content of the buffer is logged 16 bytes per line in the following format:

(offset) (first 8 bytes) (last 8 bytes) (the 16 bytes as ASCII char values)

The output for a 16 bytes array containing values from 0x00 to 0x0f would be:

"Example (16 bytes):" " 00000000 00 01 02 03 04 05 06 07 08 09 0a 0b 0c 0d 0e 0f ................"

The value for each byte as corresponding ASCII character is printed at the end if the value is printable. Otherwise, it is replaced with '.'.

Parameters

  [in] | descr | A description for the content to be logged
  [in] | what | The buffer to be logged
  [in] | len | The length of the buffer given in what

Note
  If a too long description is provided (which would result in a first line longer than 80 bytes), the function will fail.

## ◆ ssh_mkdir()

int ssh_mkdir | ( | const char * | pathname,
|  | mode_t | mode )

Attempts to create a directory with the given pathname.

This is the portable version of mkdir, mode is ignored on Windows systems.

Parameters

  [in] | pathname | The path name to create the directory.
  [in] | mode | The permissions to use.

Returns
  0 on success, < 0 on error with errno set.

## ◆ ssh_mkdirs()

int ssh_mkdirs | ( | const char * | pathname,
|  | mode_t | mode )

Attempts to create a directory with the given pathname. The missing directories in the given pathname are created recursively.

Parameters

  [in] | pathname | The path name to create the directory.
  [in] | mode | The permissions to use.

Returns
  0 on success, < 0 on error with errno set.

Note
  mode is ignored on Windows systems.

## ◆ ssh_path_expand_tilde()

char * ssh_path_expand_tilde | ( | const char * | d | ) |

Expand a directory starting with a tilde '~'.

Parameters

  [in] | d | The directory to expand.

Returns
  The expanded directory, NULL on error. The caller needs to free the memory using ssh_string_free_char().

See also
  ssh_string_free_char()

## ◆ ssh_print_hexa()

void ssh_print_hexa | ( | const char * | descr,
|  | const unsigned char * | what,
|  | size_t | len )

Deprecated
  Please use ssh_print_hash() instead

## ◆ ssh_proxyjumps_free()

void ssh_proxyjumps_free | ( | struct ssh_list * | proxy_jump_list | ) |

Free proxy jump list.

Frees everything in a proxy jump list, but doesn't free the ssh_list

Parameters

  proxy_jump_list |

## ◆ ssh_readn()

ssize_t ssh_readn | ( | int | fd,
|  | void * | buf,
|  | size_t | nbytes )

Read the requested number of bytes from a local file.

A call to read() may perform a short read even when sufficient data is present in the file. This function can be used to avoid such short reads.

This function tries to read the requested number of bytes from the file until one of the following occurs :

- Requested number of bytes are read.
- EOF is encountered before reading the requested number of bytes.
- An error occurs.

On encountering an error due to an interrupt, this function ignores that error and continues trying to read the data.

Parameters

  [in] | fd | The file descriptor of the local file to read from.
  [out] | buf | Pointer to a buffer in which read data will be stored.
  [in] | nbytes | Number of bytes to read.

Returns
  Number of bytes read on success, SSH_ERROR on error with errno set to indicate the error.

## ◆ ssh_timeout_update()

int ssh_timeout_update | ( | struct ssh_timestamp * | ts,
|  | int | timeout )

updates a timeout value so it reflects the remaining time

Parameters

  [in] | ts | pointer to an existing timestamp
  [in] | timeout | timeout in milliseconds. Negative values mean infinite timeout

Returns
  remaining time in milliseconds, 0 if elapsed, -1 if never.

## ◆ ssh_version()

const char * ssh_version | ( | int | req_version | ) |

Check if libssh is the required version or get the version string.

Parameters

  [in] | req_version | The version required.

Returns
  If the version of libssh is newer than the version required it will return a version string. NULL if the version is older.

Example:

if (ssh_version(SSH_VERSION_INT(0,2,1)) == NULL) {
fprintf(stderr, "libssh version is too old!\n");
exit(1);
}
if (debug) {
printf("libssh %s\n", ssh_version(0));
}
ssh_version
LIBSSH_API const char * ssh_version(int req_version)
Check if libssh is the required version or get the version string.
Definition misc.c:769

## ◆ ssh_writen()

ssize_t ssh_writen | ( | int | fd,
|  | const void * | buf,
|  | size_t | nbytes )

Write the requested number of bytes to a local file.

A call to write() may perform a short write on a local file. This function can be used to avoid short writes.

This function tries to write the requested number of bytes until those many bytes are written or some error occurs.

On encountering an error due to an interrupt, this function ignores that error and continues trying to write the data.

Parameters

  [in] | fd | The file descriptor of the local file to write to.
  [in] | buf | Pointer to a buffer in which data to write is stored.
  [in] | nbytes | Number of bytes to write.

Returns
  Number of bytes written on success, SSH_ERROR on error with errno set to indicate the error.