GUAC-1171: Add missing comments around static functions. Add param and return annotations to existing comments.
This commit is contained in:
parent
0fcea2738b
commit
87be5d43ea
@ -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;
|
||||
|
@ -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);
|
||||
|
||||
|
@ -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);
|
||||
|
Loading…
Reference in New Issue
Block a user