ssh.h (4997B)
1/* 2 * Licensed to the Apache Software Foundation (ASF) under one 3 * or more contributor license agreements. See the NOTICE file 4 * distributed with this work for additional information 5 * regarding copyright ownership. The ASF licenses this file 6 * to you under the Apache License, Version 2.0 (the 7 * "License"); you may not use this file except in compliance 8 * with the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, 13 * software distributed under the License is distributed on an 14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 15 * KIND, either express or implied. See the License for the 16 * specific language governing permissions and limitations 17 * under the License. 18 */ 19 20#ifndef GUAC_COMMON_SSH_H 21#define GUAC_COMMON_SSH_H 22 23#include "user.h" 24 25#include <guacamole/client.h> 26#include <libssh2.h> 27 28/** 29 * Handler for retrieving additional credentials. 30 * 31 * @param client 32 * The Guacamole Client associated with this need for additional 33 * credentials. 34 * 35 * @param cred_name 36 * The name of the credential being requested, which will be shared 37 * with the client in order to generate a meaningful prompt. 38 * 39 * @return 40 * A newly-allocated string containing the credentials provided by 41 * the user, which must be freed by a call to guac_mem_free(). 42 */ 43typedef char* guac_ssh_credential_handler(guac_client* client, char* cred_name); 44 45/** 46 * An SSH session, backed by libssh2 and associated with a particular 47 * Guacamole client. 48 */ 49typedef struct guac_common_ssh_session { 50 51 /** 52 * The Guacamole client using this SSH session. 53 */ 54 guac_client* client; 55 56 /** 57 * The user that will be authenticating via SSH. 58 */ 59 guac_common_ssh_user* user; 60 61 /** 62 * The underlying SSH session from libssh2. 63 */ 64 LIBSSH2_SESSION* session; 65 66 /** 67 * The file descriptor of the socket being used for the SSH connection. 68 */ 69 int fd; 70 71 /** 72 * Callback function to retrieve credentials. 73 */ 74 guac_ssh_credential_handler* credential_handler; 75 76} guac_common_ssh_session; 77 78/** 79 * Initializes the underlying SSH and encryption libraries used by Guacamole. 80 * This function must be called before any other guac_common_ssh_*() functions 81 * are called. 82 * 83 * @param client 84 * The Guacamole client that will be using SSH. 85 * 86 * @return 87 * Zero if initialization, or non-zero if an error occurs. 88 */ 89int guac_common_ssh_init(guac_client* client); 90 91/** 92 * Cleans up the underlying SSH and encryption libraries used by Guacamole. 93 * This function must be called once no other guac_common_ssh_*() functions 94 * will be used. 95 */ 96void guac_common_ssh_uninit(); 97 98/** 99 * Connects to the SSH server running at the given hostname and port, and 100 * authenticates as the given user. If an error occurs while connecting or 101 * authenticating, the Guacamole client will automatically and fatally abort. 102 * The user object provided must eventually be explicitly destroyed, but should 103 * not be destroyed until this session is destroyed, assuming the session is 104 * successfully created. 105 * 106 * @param client 107 * The Guacamole client that will be using SSH. 108 * 109 * @param hostname 110 * The hostname of the SSH server to connect to. 111 * 112 * @param port 113 * The port to connect to on the given hostname. 114 * 115 * @param user 116 * The user to authenticate as, once connected. 117 * 118 * @param keepalive 119 * How frequently the connection should send keepalive packets, in 120 * seconds. Zero disables keepalive packets, and 2 is the minimum 121 * configurable value. 122 * 123 * @param host_key 124 * The known public host key of the server, as provided by the client. If 125 * provided the identity of the server will be checked against this key, 126 * and a mis-match between this and the server identity will cause the 127 * connection to fail. If not provided, no checks will be done and the 128 * connection will proceed. 129 * 130 * @param credential_handler 131 * The handler function for retrieving additional credentials from the user 132 * as required by the SSH server, or NULL if the user will not be asked 133 * for additional credentials. 134 * 135 * @return 136 * A new SSH session if the connection and authentication succeed, or NULL 137 * if the connection or authentication were not successful. 138 */ 139guac_common_ssh_session* guac_common_ssh_create_session(guac_client* client, 140 const char* hostname, const char* port, guac_common_ssh_user* user, 141 int keepalive, const char* host_key, 142 guac_ssh_credential_handler* credential_handler); 143 144/** 145 * Disconnects and destroys the given SSH session, freeing all associated 146 * resources. Any associated user must be explicitly destroyed, and will not 147 * be destroyed automatically. 148 * 149 * @param session 150 * The SSH session to destroy. 151 */ 152void guac_common_ssh_destroy_session(guac_common_ssh_session* session); 153 154#endif 155