Chapter 1: A typical SSH session

Подсистемы sftp и scp используют каналы, но libssh скрывает их от программиста. Если появится желание использовать эти подсистемы вместо каналов, обычно открывают "sftp сессию" или "scp сессию".

Создание сессии и установка опций

Наиболее важным объектом в SSH-соединении является SSH-сессия. Для того, чтобы выделить память под новую сессию используйте ssh_new(). Не забывайте всегда проверять, что выделение памяти прошло успешно.

Библиотека libssh следует правилу выделяй-освобождай (allocate-it-deallocate-it). Каждый объект, память под который была выделена с использованием xxxxx_new(), должен освобождать её используя xxxxx_free(). В этом случае, ssh_new() делает выделение памяти, а ssh_free() делает с ней обратную операцию.

Функция ssh_options_set() устанавливает опции SSH-сессии. Наиболее важные из них:

Полный список опций может быть найден в документации на ssh_options_set(). Обязательной из них является опция SSH_OPTIONS_HOST. В тоже время, если опция SSH_OPTIONS_USER не используется, в качестве локального имени пользователя будет использован тот аккаунт из под которого было запущено приложение.

Ниже приводится небольшой пример, показывающий как использовать это.

Пожалуйста помните, что все параметры ssh_options_set() передаются по указателю, даже если есть необходимость установить опции целое значение.

Соединение с сервером

Раз уже все настройки сделаны, можно соединится используя ssh_connect(). Эта функция возвратит SSH_OK, если соединение работоспособно, либо SSH_ERROR в обратном случае.

Для того, чтобы показать пользователю что что-то пошло не так, можно получить сообщение об ошибке на Английском языке используя ssh_get_error(). В случае, когда необходимо завершить сессию используйте ssh_disconnect().

Проверка подлинности сервера

После установки соединения, следующим обязательным шагом является проверка того, что сервер, с которым оно было установлено, является для использования известным и безопасным ( помните, что суть SSH в безопасности и проверки прав доступа).

Так же можно использовать ssh_get_pubkey_hash() для просмотра хэш-значения публичного ключа пользователем, в случае если он ему известен ( иногда, на всякий случай некоторые параноидальные люди записывают свои хэш-значения публичных ключей на бумагу перед тем как выйти куда-нибудь ...).

Если удаленный узел используется впервые, можно спросить пользователя (Он или Она) доверяют ли ему. Раз Он или Она заключили, что узел является действительным и стоит его добавить в файл известных узлов, используйте ssh_write_knownhost() в этом файле или другим способом, если используется собственная база данных.

Следующий пример является одним из примеров приведенных в директории examples/

Проверка подлинности пользователя

Процесс проверки подлинности пользователя [прим.перевод. он же аутентификации] является способом, когда сервис-провайдер может идентифицировать пользователя и подтвердить Его (Её) идентичность. Процесс авторизации заключается в разрешение аутентичности пользователя для доступа к ресурсам. В SSH соединены две концепции. После аутентификации, сервер может разрешить доступ пользователя к нескольким ресурсам таких как переадресация портов (port forwarding), командной строке, подсистемы sftp и так далее.

Библиотека libssh поддерживает несколько методов аутентификации:

Все эти методы могут комбинироваться. Для примера, можно заставить пользователя производить аутентификацию по-крайне мере по двум таким методам. В таком случае, говорят о "частном случае аутентификации". Частный случай аутентификации является откликом от функции аутентификации подтверждая то, что ваша подлинность удостоверена, а другим её ещё нужно получить.

Ниже показан пример аутентификации пользователя по паролю:

#include <libssh/libssh.h>

#include <stdlib.h>

#include <stdio.h>
 
int main()
{
ssh_session my_ssh_session;
int rc;
char *password;
 
// Открытие сессии и установка опций
 my_ssh_session = ssh_new();
if (my_ssh_session == NULL)
exit(-1);
ssh_options_set(my_ssh_session, SSH_OPTIONS_HOST, "localhost");
 
// Соединение с сервером
rc = ssh_connect(my_ssh_session);
if (rc != SSH_OK)
{
fprintf(stderr, "Error connecting to localhost: %s\n",
ssh_get_error(my_ssh_session));
ssh_free(my_ssh_session);
exit(-1);
}
 
// Проверка идентичности сервера
// Для получения исходного кода verify_knowhost(), обратитесь к предыдущему примеру
if (verify_knownhost(my_ssh_session) < 0)
{
ssh_disconnect(my_ssh_session);
ssh_free(my_ssh_session);
exit(-1);
}
 
// Аутентифицируемся сами
password = getpass("Password: ");
rc = ssh_userauth_password(my_ssh_session, NULL, password);
if (rc != SSH_AUTH_SUCCESS)
{
fprintf(stderr, "Error authenticating with password: %s\n",
ssh_get_error(my_ssh_session));
ssh_disconnect(my_ssh_session);
ssh_free(my_ssh_session);
exit(-1);
}
 
...
 
ssh_disconnect(my_ssh_session);
ssh_free(my_ssh_session);
}

Смотри так же: Более глубокий взгляд на аутентификацию

Сделаем что-нибудь

В этом пункте будет устанавливаться аутентификация как для клиента, так и для сервера. Пришло время воспользоваться преимуществами, которые предлагаются протоколом SSH, а именно удаленно: выполнить команду, открыть командную строку. А так же осуществить передачу файлов, переадресацию портов и многое другое.

В ниже представленном примере показано как выполнять удаленно команду:

int show_remote_processes(ssh_session session)


{
ssh_channel channel;
int rc;
char buffer[256];
unsigned int nbytes;
 
channel = ssh_channel_new(session);
if (channel == NULL)
return SSH_ERROR;
 
rc = ssh_channel_open_session(channel);
if (rc != SSH_OK)
{
ssh_channel_free(channel);
return rc;
}
 
rc = ssh_channel_request_exec(channel, "ps aux");
if (rc != SSH_OK)
{
ssh_channel_close(channel);
ssh_channel_free(channel);
return rc;
}
 
nbytes = ssh_channel_read(channel, buffer, sizeof(buffer), 0);
while (nbytes > 0)
{
if (write(1, buffer, nbytes) != nbytes)
{
ssh_channel_close(channel);
ssh_channel_free(channel);
return SSH_ERROR;
}
nbytes = ssh_channel_read(channel, buffer, sizeof(buffer), 0);
}
     
if (nbytes < 0)
{
ssh_channel_close(channel);
ssh_channel_free(channel);
return SSH_ERROR;
}
 
ssh_channel_send_eof(channel);
ssh_channel_close(channel);
ssh_channel_free(channel);
return SSH_OK;
}

Смотри так же

Обработка ошибок

Все функции libssh, которые возвращают значение ошибки так же устанавливают сообщение о ней с описание проблемы на Английском языке.

Значение ошибки типично SSH_ERROR для целых значений или NULL для указателей.

Функция ssh_get_error() возвращает указатель на статическое сообщение об ошибке.

Функция ssh_error_code() возвращает код ошибки: SSH_NO_ERROR, SSH_REQUEST_DENIED, SSH_INVALID_REQUEST, SSH_CONNECTION_LOST, SSH_FATAL или SSH_INVALID_DATA. SSH_REQUEST_DENIED подразумевает, что SSH-сервер отклонил клиентский запрос, но ситуация поправима. Остальные подразумевают, что что-то случилось с соединением (какие-то криптографические проблемы, проблемы сервера, …). SSH_INVALID_REQUEST подразумевает, что библиотека получила какую-то ерунду от сервера, но может быть восстановлена. SSH_FATAL подразумевает, что соединение имеет существенную проблему не предполагающее восстановление.

Почти всегда в качестве ошибке возвращается SSH_FATAL, но иногда функции ( главным образом такие как ssh_request_xxx) могут терпеть неудачу, потому что сервер отвергает запрос. В таком случае будет возвращен SSH_REQUEST_DENIED

Функции ssh_get_error() и ssh_get_error_code() берут в качестве параметра ssh_session. Что является для потока безопасным, потому что ошибки могут быть присоединены к сессии не будучи статическими. Любая ошибка, которая произошла во время вызова ssh_options_xxx() или ssh_connect() (например, вне сессии) может быть возвращены путем NULL-указателя в качестве аргумента.

Подсистема SFTP имеет свои собственные коды ошибок в дополнение к имеющимся в libssh.