GUAC-1171: Add missing comments around static functions. Add param and return annotations to existing comments.

src/common-ssh/guac_ssh.c

@@ -53,6 +53,20 @@ static pthread_mutex_t* guac_common_ssh_openssl_locks;
 
 /**
  * Called by OpenSSL when locking or unlocking the Nth mutex.
+ *
+ * @param mode
+ *     A bitmask denoting the action to be taken on the Nth lock, such as
+ *     CRYPTO_LOCK or CRYPTO_UNLOCK.
+ *
+ * @param n
+ *     The index of the lock to lock or unlock.
+ *
+ * @param file
+ *     The filename of the function setting the lock, for debugging purposes.
+ *
+ * @param line
+ *     The line number of the function setting the lock, for debugging
+ *     purposes.
  */
 static void guac_common_ssh_openssl_locking_callback(int mode, int n,
         const char* file, int line){
@@ -69,6 +83,9 @@ static void guac_common_ssh_openssl_locking_callback(int mode, int n,
 
 /**
  * Called by OpenSSL when determining the current thread ID.
+ *
+ * @return
+ *     An ID which uniquely identifies the current thread.
  */
 static unsigned long guac_common_ssh_openssl_id_callback() {
     return (unsigned long) pthread_self();
@@ -77,6 +94,9 @@ static unsigned long guac_common_ssh_openssl_id_callback() {
 /**
  * Creates the given number of mutexes, such that OpenSSL will have at least
  * this number of mutexes at its disposal.
+ *
+ * @param count
+ *     The number of mutexes (locks) to create.
  */
 static void guac_common_ssh_openssl_init_locks(int count) {
 
@@ -94,6 +114,9 @@ static void guac_common_ssh_openssl_init_locks(int count) {
 
 /**
  * Frees the given number of mutexes.
+ *
+ * @param count
+ *     The number of mutexes (locks) to free.
  */
 static void guac_common_ssh_openssl_free_locks(int count) {
 
@@ -137,6 +160,36 @@ void guac_common_ssh_uninit() {
     guac_common_ssh_openssl_free_locks(CRYPTO_num_locks());
 }
 
+/**
+ * Callback invoked by libssh2 when libssh2_userauth_publickkey() is invoked.
+ * This callback must sign the given data, returning the signature as newly-
+ * allocated buffer space.
+ *
+ * @param session
+ *     The SSH session for which the signature is being generated.
+ *
+ * @param sig
+ *     A pointer to the buffer space containing the signature. This callback
+ *     MUST allocate and assign this space.
+ *
+ * @param sig_len
+ *     The length of the signature within the allocated buffer space, in bytes.
+ *     This value must be set to the size of the signature after the signing
+ *     operation completes.
+ *
+ * @param data
+ *     The arbitrary data that must be signed.
+ *
+ * @param data_len
+ *     The length of the arbitrary data to be signed, in bytes.
+ *
+ * @param abstract
+ *     The value of the abstract parameter provided with the corresponding call
+ *     to libssh2_userauth_publickey().
+ *
+ * @return
+ *     Zero on success, non-zero if the signing operation failed.
+ */
 static int guac_common_ssh_sign_callback(LIBSSH2_SESSION* session,
         unsigned char** sig, size_t* sig_len,
         const unsigned char* data, size_t data_len, void **abstract) {
@@ -158,7 +211,40 @@ static int guac_common_ssh_sign_callback(LIBSSH2_SESSION* session,
 
 /**
  * Callback for the keyboard-interactive authentication method. Currently
- * suports just one prompt for the password.
+ * supports just one prompt for the password. This callback is invoked as
+ * needed to fullfill a call to libssh2_userauth_keyboard_interactive().
+ *
+ * @param name
+ *     An arbitrary name which should be printed to the terminal for the
+ *     benefit of the user. This is currently ignored.
+ *
+ * @param name_len
+ *     The length of the name string, in bytes.
+ *
+ * @param instruction
+ *     Arbitrary instructions which should be printed to the terminal for the
+ *     benefit of the user. This is currently ignored.
+ *
+ * @param instruction_len
+ *     The length of the instruction string, in bytes.
+ *
+ * @param num_prompts
+ *     The number of keyboard-interactive prompts for which responses are
+ *     requested. This callback currently only supports one prompt, and assumes
+ *     that this prompt is requesting the password.
+ *
+ * @param prompts
+ *     An array of all keyboard-interactive prompts for which responses are
+ *     requested.
+ *
+ * @param responses
+ *     A parallel array into which all prompt responses should be stored. Each
+ *     entry within this array corresponds to the entry in the prompts array
+ *     with the same index.
+ *
+ * @param abstract
+ *     The value of the abstract parameter provided when the SSH session was
+ *     created with libssh2_session_init_ex().
  */
 static void guac_common_ssh_kbd_callback(const char *name, int name_len,
         const char *instruction, int instruction_len, int num_prompts,
@@ -186,6 +272,18 @@ static void guac_common_ssh_kbd_callback(const char *name, int name_len,
 
 }
 
+/**
+ * Authenticates the user associated with the given session over SSH. All
+ * required credentials must already be present within the user object
+ * associated with the given session.
+ *
+ * @param session
+ *     The session associated with the user to be authenticated.
+ *
+ * @return
+ *     Zero if authentication succeeds, or non-zero if authentication has
+ *     failed.
+ */
 static int guac_common_ssh_authenticate(guac_common_ssh_session* common_session) {
 
     guac_client* client = common_session->client;

src/common-ssh/guac_ssh_buffer.h

@@ -31,12 +31,24 @@
 /**
  * Writes the given byte to the given buffer, advancing the buffer pointer by
  * one byte.
+ *
+ * @param buffer
+ *     The buffer to write to.
+ *
+ * @param value
+ *     The value to write.
  */
 void guac_common_buffer_write_byte(char** buffer, uint8_t value);
 
 /**
  * Writes the given integer to the given buffer, advancing the buffer pointer
  * four bytes.
+ *
+ * @param buffer
+ *     The buffer to write to.
+ *
+ * @param value
+ *     The value to write.
  */
 void guac_common_buffer_write_uint32(char** buffer, uint32_t value);
 
@@ -44,28 +56,62 @@ void guac_common_buffer_write_uint32(char** buffer, uint32_t value);
  * Writes the given string and its length to the given buffer, advancing the
  * buffer pointer by the size of the length (four bytes) and the size of the
  * string.
+ *
+ * @param buffer
+ *     The buffer to write to.
+ *
+ * @param string
+ *     The string value to write.
+ *
+ * @param length
+ *     The length of the string to write, in bytes.
  */
-void guac_common_buffer_write_string(char** buffer, const char* string, int length);
+void guac_common_buffer_write_string(char** buffer, const char* string,
+        int length);
 
 /**
  * Writes the given BIGNUM the given buffer, advancing the buffer pointer by
  * the size of the length (four bytes) and the size of the BIGNUM.
+ *
+ * @param buffer
+ *     The buffer to write to.
+ *
+ * @param value
+ *     The value to write.
  */
 void guac_common_buffer_write_bignum(char** buffer, BIGNUM* value);
 
 /**
  * Writes the given data the given buffer, advancing the buffer pointer by the
  * given length.
+ *
+ * @param data
+ *     The arbitrary data to write.
+ *
+ * @param length
+ *     The length of data to write, in bytes.
  */
 void guac_common_buffer_write_data(char** buffer, const char* data, int length);
 
 /**
  * Reads a single byte from the given buffer, advancing the buffer by one byte.
+ *
+ * @param buffer
+ *     The buffer to read from.
+ *
+ * @return
+ *     The value read from the buffer.
  */
 uint8_t guac_common_buffer_read_byte(char** buffer);
 
 /**
  * Reads an integer from the given buffer, advancing the buffer by four bytes.
+ *
+ * @param buffer
+ *     The buffer to read from.
+ *
+ * @return
+ *     The value read from the buffer.
  */
 uint32_t guac_common_buffer_read_uint32(char** buffer);
 
@@ -74,6 +120,16 @@ uint32_t guac_common_buffer_read_uint32(char** buffer);
  * by the size of the length (four bytes) and the size of the string, and
  * returning a pointer to the buffer. The length of the string is stored in
  * the given int.
+ *
+ * @param buffer
+ *     The buffer to read from.
+ *
+ * @param length
+ *     A pointer to an integer into which the length of the read string will
+ *     be stored.
+ *
+ * @return
+ *     A pointer to the value within the buffer.
  */
 char* guac_common_buffer_read_string(char** buffer, int* length);
 

src/common-ssh/guac_ssh_key.h

@@ -109,6 +109,20 @@ typedef struct guac_common_ssh_key {
 /**
  * Allocates a new key containing the given private key data and specified
  * passphrase. If unable to read the key, NULL is returned.
+ *
+ * @param data
+ *     The base64-encoded data to decode when reading the key.
+ *
+ * @param length
+ *     The length of the provided data, in bytes.
+ *
+ * @param passphrase
+ *     The passphrase to use when decrypting the key, if any, or an empty
+ *     string or NULL if no passphrase is needed.
+ *
+ * @return
+ *     The decoded, decrypted private key, or NULL if the key could not be
+ *     decoded.
  */
 guac_common_ssh_key* guac_common_ssh_key_alloc(char* data, int length,
         char* passphrase);
@@ -124,12 +138,33 @@ const char* guac_common_ssh_key_error();
 
 /**
  * Frees all memory associated with the given key.
+ *
+ * @param key
+ *     The key to free.
  */
 void guac_common_ssh_key_free(guac_common_ssh_key* key);
 
 /**
  * Signs the given data using the given key, returning the length of the
  * signature in bytes, or a value less than zero on error.
+ *
+ * @param key
+ *     The key to use when signing the given data.
+ *
+ * @param data
+ *     The arbitrary data to sign.
+ *
+ * @param length
+ *     The length of the arbitrary data being signed, in bytes.
+ *
+ * @param sig
+ *     The buffer into which the signature should be written. The buffer must
+ *     be at least DSA_SIG_SIZE for DSA keys. For RSA keys, the signature size
+ *     is dependent only on key size, and is equal to the length of the
+ *     modulus, in bytes.
+ *
+ * @return
+ *     The number of bytes in the resulting signature.
  */
 int guac_common_ssh_key_sign(guac_common_ssh_key* key, const char* data,
         int length, unsigned char* sig);