GUACAMOLE-547: Fixes for style and documentation.

src/common-ssh/common-ssh/ssh.h

@@ -27,8 +27,17 @@
 
 /**
  * Handler for retrieving additional credentials.
+ * 
+ * @param client
+ *     The Guacamole Client associated with this need for additional
+ *     credentials.
+ * 
+ * @param cred_name
+ *     The name of the credential being requested, which will be shared
+ *     with the client in order to generate a meaningful prompt.
+ * 
  */
-typedef char* guac_ssh_credential_handler(guac_client* client, char* credName);
+typedef char* guac_ssh_credential_handler(guac_client* client, char* cred_name);
 
 /**
  * An SSH session, backed by libssh2 and associated with a particular
@@ -103,13 +112,30 @@ void guac_common_ssh_uninit();
  * @param user
  *     The user to authenticate as, once connected.
  * 
+ * @param keepalive
+ *     How frequently the connection should send keepalive packets, in
+ *     seconds.  Zero disables keepalive packets, and 2 is the minimum
+ *     configurable value.
+ * 
+ * @param host_key
+ *     The known public host key of the server, as provided by the client.  If
+ *     provided the identity of the server will be checked against this key,
+ *     and a mis-match between this and the server identity will cause the
+ *     connection to fail.  If not provided, no checks will be done and the
+ *     connection will proceed.
+ * 
+ * @param credential_handler
+ *     The handler function for retrieving additional credentials from the user
+ *     as required by the SSH server.
+ *
  * @return
  *     A new SSH session if the connection and authentication succeed, or NULL
  *     if the connection or authentication were not successful.
  */
 guac_common_ssh_session* guac_common_ssh_create_session(guac_client* client,
-        const char* hostname, const char* port, guac_common_ssh_user* user, int keepalive,
+        const char* hostname, const char* port, guac_common_ssh_user* user,
-        const char* host_key, guac_ssh_credential_handler* credential_callback);
+        int keepalive, const char* host_key,
+        guac_ssh_credential_handler* credential_handler);
 
 /**
  * Disconnects and destroys the given SSH session, freeing all associated

src/common-ssh/ssh.c

@@ -327,7 +327,6 @@ static int guac_common_ssh_authenticate(guac_common_ssh_session* common_session)
     guac_client_log(client, GUAC_LOG_DEBUG,
             "Supported authentication methods: %s", user_authlist);
 
-
     /* Authenticate with private key, if provided */
     if (key != NULL) {
 
@@ -359,7 +358,7 @@ static int guac_common_ssh_authenticate(guac_common_ssh_session* common_session)
 
     }
 
-    /* Down to username + password authentication. */
+    /* Attempt authentication with username + password. */
     if (user->password == NULL && common_session->credential_handler)
             user->password = common_session->credential_handler(client, "Password: ");
     
@@ -426,8 +425,9 @@ static int guac_common_ssh_authenticate(guac_common_ssh_session* common_session)
 }
 
 guac_common_ssh_session* guac_common_ssh_create_session(guac_client* client,
-        const char* hostname, const char* port, guac_common_ssh_user* user, int keepalive,
+        const char* hostname, const char* port, guac_common_ssh_user* user,
-        const char* host_key, guac_ssh_credential_handler* credential_handler) {
+        int keepalive, const char* host_key,
+        guac_ssh_credential_handler* credential_handler) {
 
     int retval;
 

src/protocols/ssh/ssh.c

@@ -138,25 +138,25 @@ static guac_common_ssh_user* guac_ssh_get_user(guac_client* client) {
 }
 
 /**
- * A call-back function used to gather additional credentials from a client
+ * A function used to generate a terminal prompt to gather additional
- * during a connection.  It takes the guac_client object and a string to
+ * credentials from the guac_client during a connection, and using
- * display to the user, and returns the credentials entered by the user.
+ * the specified string to generate the prompt for the user.
  * 
  * @param client
  *     The guac_client object associated with the current connection
  *     where additional credentials are required.
  * 
- * @param credName
+ * @param cred_name
  *     The prompt text to display to the screen when prompting for the
  *     additional credentials.
  * 
  * @return 
  *     The string of credentials gathered from the user.
  */
-char* guac_ssh_get_credential(guac_client *client, char* credName) {
+static char* guac_ssh_get_credential(guac_client *client, char* cred_name) {
 
     guac_ssh_client* ssh_client = (guac_ssh_client*) client->data;
-    return guac_terminal_prompt(ssh_client->term, credName, false);
+    return guac_terminal_prompt(ssh_client->term, cred_name, false);
     
 }