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.
|
* 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;
|
||||||
|
@ -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);
|
||||||
|
|
||||||
|
@ -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);
|
||||||
|
Loading…
Reference in New Issue
Block a user