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

This commit is contained in:
Michael Jumper 2015-07-10 14:20:16 -07:00
parent 0fcea2738b
commit 87be5d43ea
3 changed files with 191 additions and 2 deletions

View File

@ -53,6 +53,20 @@ static pthread_mutex_t* guac_common_ssh_openssl_locks;
/** /**
* Called by OpenSSL when locking or unlocking the Nth mutex. * 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, static void guac_common_ssh_openssl_locking_callback(int mode, int n,
const char* file, int line){ 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. * 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() { static unsigned long guac_common_ssh_openssl_id_callback() {
return (unsigned long) pthread_self(); 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 * Creates the given number of mutexes, such that OpenSSL will have at least
* this number of mutexes at its disposal. * 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) { 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. * 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) { 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()); 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, static int guac_common_ssh_sign_callback(LIBSSH2_SESSION* session,
unsigned char** sig, size_t* sig_len, unsigned char** sig, size_t* sig_len,
const unsigned char* data, size_t data_len, void **abstract) { 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 * 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, static void guac_common_ssh_kbd_callback(const char *name, int name_len,
const char *instruction, int instruction_len, int num_prompts, 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) { static int guac_common_ssh_authenticate(guac_common_ssh_session* common_session) {
guac_client* client = common_session->client; guac_client* client = common_session->client;

View File

@ -31,12 +31,24 @@
/** /**
* Writes the given byte to the given buffer, advancing the buffer pointer by * Writes the given byte to the given buffer, advancing the buffer pointer by
* one byte. * 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); void guac_common_buffer_write_byte(char** buffer, uint8_t value);
/** /**
* Writes the given integer to the given buffer, advancing the buffer pointer * Writes the given integer to the given buffer, advancing the buffer pointer
* four bytes. * 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); 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 * 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 * buffer pointer by the size of the length (four bytes) and the size of the
* string. * 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 * 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. * 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); void guac_common_buffer_write_bignum(char** buffer, BIGNUM* value);
/** /**
* Writes the given data the given buffer, advancing the buffer pointer by the * Writes the given data the given buffer, advancing the buffer pointer by the
* given length. * 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); 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. * 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); uint8_t guac_common_buffer_read_byte(char** buffer);
/** /**
* Reads an integer from the given buffer, advancing the buffer by four bytes. * 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); 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 * 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 * returning a pointer to the buffer. The length of the string is stored in
* the given int. * 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); char* guac_common_buffer_read_string(char** buffer, int* length);

View File

@ -109,6 +109,20 @@ typedef struct guac_common_ssh_key {
/** /**
* Allocates a new key containing the given private key data and specified * Allocates a new key containing the given private key data and specified
* passphrase. If unable to read the key, NULL is returned. * 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, guac_common_ssh_key* guac_common_ssh_key_alloc(char* data, int length,
char* passphrase); char* passphrase);
@ -124,12 +138,33 @@ const char* guac_common_ssh_key_error();
/** /**
* Frees all memory associated with the given key. * 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); void guac_common_ssh_key_free(guac_common_ssh_key* key);
/** /**
* Signs the given data using the given key, returning the length of the * Signs the given data using the given key, returning the length of the
* signature in bytes, or a value less than zero on error. * 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 guac_common_ssh_key_sign(guac_common_ssh_key* key, const char* data,
int length, unsigned char* sig); int length, unsigned char* sig);