From 87be5d43ea90cb3c6e4854e57501f2700412ea35 Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Fri, 10 Jul 2015 14:20:16 -0700 Subject: [PATCH] GUAC-1171: Add missing comments around static functions. Add param and return annotations to existing comments. --- src/common-ssh/guac_ssh.c | 100 ++++++++++++++++++++++++++++++- src/common-ssh/guac_ssh_buffer.h | 58 +++++++++++++++++- src/common-ssh/guac_ssh_key.h | 35 +++++++++++ 3 files changed, 191 insertions(+), 2 deletions(-) diff --git a/src/common-ssh/guac_ssh.c b/src/common-ssh/guac_ssh.c index 76b293bc..7bbd789d 100644 --- a/src/common-ssh/guac_ssh.c +++ b/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; diff --git a/src/common-ssh/guac_ssh_buffer.h b/src/common-ssh/guac_ssh_buffer.h index df9a519e..750c625e 100644 --- a/src/common-ssh/guac_ssh_buffer.h +++ b/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); diff --git a/src/common-ssh/guac_ssh_key.h b/src/common-ssh/guac_ssh_key.h index 393c7c1d..e76ac067 100644 --- a/src/common-ssh/guac_ssh_key.h +++ b/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);