aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorAndreas Schneider <mail@cynapses.org>2010-04-04 15:29:56 +0200
committerAndreas Schneider <mail@cynapses.org>2010-04-04 15:51:54 +0200
commit0efd50df26135b23426950565c0e953c7e2b7372 (patch)
treea3cec6ee690e7aa0ecce5d00b54ae3760fcef92b
parenta127c8827a0733861366bfe1c0ca2fe7ccfac114 (diff)
downloadlibssh-0efd50df26135b23426950565c0e953c7e2b7372.tar.gz
libssh-0efd50df26135b23426950565c0e953c7e2b7372.tar.xz
libssh-0efd50df26135b23426950565c0e953c7e2b7372.zip
Fixed the documentation of key functions.
-rw-r--r--libssh/keyfiles.c202
-rw-r--r--libssh/keys.c36
2 files changed, 152 insertions, 86 deletions
diff --git a/libssh/keyfiles.c b/libssh/keyfiles.c
index 906e9847..663d508f 100644
--- a/libssh/keyfiles.c
+++ b/libssh/keyfiles.c
@@ -627,18 +627,32 @@ static int privatekey_type_from_file(FILE *fp) {
return 0;
}
-/** \addtogroup ssh_auth
+/**
+ * @addtogroup libssh_auth
+ *
* @{
*/
-/* TODO : implement it to read both DSA and RSA at once */
-/** \brief Reads a SSH private key from a file
- * \param session SSH Session
- * \param filename Filename containing the private key
- * \param type Type of the private key. One of TYPE_DSS or TYPE_RSA. Pass 0 to automatically detect the type.
- * \param passphrase Passphrase to decrypt the private key. Set to null if none is needed or it is unknown.
- * \returns a PRIVATE_KEY object containing the private key, or NULL if it failed.
- * \see privatekey_free()
- * \see publickey_from_privatekey()
+
+/**
+ * @brief Reads a SSH private key from a file.
+ *
+ * @param[in] session The SSH Session to use.
+ *
+ * @param[in] filename The filename of the the private key.
+ *
+ * @param[in] type The type of the private key. This could be TYPE_DSS or
+ * TYPE_RSA. Pass 0 to automatically detect the type.
+ *
+ * @param[in] passphrase The passphrase to decrypt the private key. Set to null
+ * if none is needed or it is unknown.
+ *
+ * @returns A private_key object containing the private key, or
+ * NULL on error.
+ *
+ * @todo Implement to read both DSA and RSA at once.
+ *
+ * @see privatekey_free()
+ * @see publickey_from_privatekey()
*/
ssh_private_key privatekey_from_file(ssh_session session, const char *filename,
int type, const char *passphrase) {
@@ -868,8 +882,10 @@ ssh_private_key _privatekey_from_file(void *session, const char *filename,
return privkey;
}
-/** \brief deallocate a private key
- * \param prv a PRIVATE_KEY object
+/**
+ * @brief Deallocate a private key object.
+ *
+ * @param[in] prv The private_key object to free.
*/
void privatekey_free(ssh_private_key prv) {
if (prv == NULL) {
@@ -960,13 +976,21 @@ int ssh_publickey_to_file(ssh_session session, const char *file,
return 0;
}
-/** \brief Retrieve a public key from a file
- * \param session the SSH session
- * \param filename Filename of the key
- * \param type Pointer to a integer. If it is not null, it contains the type of the key after execution.
- * \return a SSH String containing the public key, or NULL if it failed.
- * \see string_free()
- * \see publickey_from_privatekey()
+/**
+ * @brief Retrieve a public key from a file.
+ *
+ * @param[in] session The SSH session to use.
+ *
+ * @param[in] filename The filename of the public key.
+ *
+ * @param[out] type The Pointer to a integer. If it is not NULL, it will
+ * contain the type of the key after execution.
+ *
+ * @return A SSH String containing the public key, or NULL if it
+ * failed.
+ *
+ * @see string_free()
+ * @see publickey_from_privatekey()
*/
ssh_string publickey_from_file(ssh_session session, const char *filename,
int *type) {
@@ -1197,17 +1221,23 @@ static int alldigits(const char *s) {
return 1;
}
-/** @}
- */
+/* @} */
-/** \addtogroup ssh_session
- * @{ */
/**
- * \brief Lowercase a string.
- * \param str String to lowercase.
- * \return The malloced lowered string or NULL on error.
- * \internal
+ * @addtogroup libssh_session
+ *
+ * @{
+ */
+
+/**
+ * @internal
+ *
+ * @brief Lowercase a string.
+ *
+ * @param[in] str The string to lowercase.
+ *
+ * @return The malloced lowered string or NULL on error.
*/
static char *lowercase(const char* str) {
char *new, *p;
@@ -1228,8 +1258,10 @@ static char *lowercase(const char* str) {
return new;
}
-/** \brief frees a token array
- * \internal
+/**
+ * @internal
+ *
+ * @brief Free a token array.
*/
static void tokens_free(char **tokens) {
if (tokens == NULL) {
@@ -1243,14 +1275,24 @@ static void tokens_free(char **tokens) {
SAFE_FREE(tokens);
}
-/** \brief returns one line of known host file
- * will return a token array containing (host|ip) keytype key
- * \param file pointer to the known host file. Could be pointing to NULL at start
- * \param filename file name of the known host file
- * \param found_type pointer to a string to be set with the found key type
- * \internal
- * \returns NULL if no match was found or the file was not found
- * \returns found_type type of key (ie "dsa","ssh-rsa1"). Don't free that value.
+/**
+ * @internal
+ *
+ * @brief Return one line of known host file.
+ *
+ * This will return a token array containing (host|ip), keytype and key.
+ *
+ * @param[out] file A pointer to the known host file. Could be pointing to
+ * NULL at start.
+ *
+ * @param[in] filename The file name of the known host file.
+ *
+ * @param[out] found_type A pointer to a string to be set with the found key
+ * type.
+ *
+ * @returns The found_type type of key (ie "dsa","ssh-rsa1"). Don't
+ * free that value. NULL if no match was found or the file
+ * was not found.
*/
static char **ssh_get_knownhost_line(ssh_session session, FILE **file,
const char *filename, const char **found_type) {
@@ -1327,12 +1369,15 @@ static char **ssh_get_knownhost_line(ssh_session session, FILE **file,
}
/**
- * \brief Check the public key in the known host line matches the
- * public key of the currently connected server.
- * \param tokens list of tokens in the known_hosts line.
- * \return 1 if the key matches
- * \return 0 if the key doesn't match
- * \return -1 on error
+ * @brief Check the public key in the known host line matches the public key of
+ * the currently connected server.
+ *
+ * @param[in] session The SSH session to use.
+ *
+ * @param[in] tokens A list of tokens in the known_hosts line.
+ *
+ * @returns 1 if the key matches, 0 if the key doesn't match and -1
+ * on error.
*/
static int check_public_key(ssh_session session, char **tokens) {
ssh_string pubkey = session->current_crypto->server_pubkey;
@@ -1428,11 +1473,13 @@ static int check_public_key(ssh_session session, char **tokens) {
}
/**
- * \brief checks if a hostname matches a openssh-style hashed known host
- * \param host host to check
- * \param hashed hashed value
- * \returns 1 if it matches
- * \returns 0 otherwise
+ * @brief Check if a hostname matches a openssh-style hashed known host.
+ *
+ * @param[in] host The host to check.
+ *
+ * @param[in] hashed The hashed value.
+ *
+ * @returns 1 if it matches, 0 otherwise.
*/
static int match_hashed_host(ssh_session session, const char *host,
const char *sourcehash) {
@@ -1526,32 +1573,33 @@ static int match_hashed_host(ssh_session session, const char *host,
*/
/**
- * \brief Check if the server is known.
+ * @brief Check if the server is known.
+ *
* Checks the user's known host file for a previous connection to the
* current server.
*
- * \param session ssh session
+ * @param[in] session The SSH session to use.
*
- * \return SSH_SERVER_KNOWN_OK: The server is known and has not changed\n
- * SSH_SERVER_KNOWN_CHANGED: The server key has changed. Either you are
- * under attack or the administrator changed
- * the key. You HAVE to warn the user about
- * a possible attack\n
- * SSH_SERVER_FOUND_OTHER: The server gave use a key of a type while
- * we had an other type recorded. It is a
- * possible attack \n
- * SSH_SERVER_NOT_KNOWN: The server is unknown. User should confirm
- * the MD5 is correct\n
- * SSH_SERVER_FILE_NOT_FOUND:The known host file does not exist. The
- * host is thus unknown. File will be created
- * if host key is accepted\n
- * SSH_SERVER_ERROR: Some error happened
+ * @returns SSH_SERVER_KNOWN_OK: The server is known and has not changed.\n
+ * SSH_SERVER_KNOWN_CHANGED: The server key has changed. Either you
+ * are under attack or the administrator
+ * changed the key. You HAVE to warn the
+ * user about a possible attack.\n
+ * SSH_SERVER_FOUND_OTHER: The server gave use a key of a type while
+ * we had an other type recorded. It is a
+ * possible attack.\n
+ * SSH_SERVER_NOT_KNOWN: The server is unknown. User should
+ * confirm the MD5 is correct.\n
+ * SSH_SERVER_FILE_NOT_FOUND: The known host file does not exist. The
+ * host is thus unknown. File will be
+ * created if host key is accepted.\n
+ * SSH_SERVER_ERROR: Some error happened.
*
- * \see ssh_options_set()
- * \see ssh_get_pubkey_hash()
+ * @see ssh_options_set()
+ * @see ssh_get_pubkey_hash()
*
- * \bug There is no current way to remove or modify an entry into the known
- * host table.
+ * @bug There is no current way to remove or modify an entry into the known
+ * host table.
*/
int ssh_is_server_known(ssh_session session) {
FILE *file = NULL;
@@ -1638,10 +1686,15 @@ int ssh_is_server_known(ssh_session session) {
return ret;
}
-/** You generaly use it when ssh_is_server_known() answered SSH_SERVER_NOT_KNOWN
- * \brief write the current server as known in the known hosts file. This will create the known hosts file if it does not exist.
- * \param session ssh session
- * \return 0 on success, -1 on error
+/**
+ * @brief Write the current server as known in the known hosts file.
+ *
+ * This will create the known hosts file if it does not exist. You generaly use
+ * it when ssh_is_server_known() answered SSH_SERVER_NOT_KNOWN.
+ *
+ * @param[in] session The ssh session to use.
+ *
+ * @return 0 on success, -1 on error.
*/
int ssh_write_knownhost(ssh_session session) {
ssh_string pubkey = session->current_crypto->server_pubkey;
@@ -1806,5 +1859,6 @@ int ssh_write_knownhost(ssh_session session) {
return 0;
}
-/** @} */
-/* vim: set ts=2 sw=2 et cindent: */
+/* @} */
+
+/* vim: set ts=4 sw=4 et cindent: */
diff --git a/libssh/keys.c b/libssh/keys.c
index d6bb8de1..5552e549 100644
--- a/libssh/keys.c
+++ b/libssh/keys.c
@@ -37,11 +37,13 @@
#include "libssh/dh.h"
#include "libssh/messages.h"
-/** \addtogroup ssh_auth
+/**
+ * @addtogroup libssh_auth
+ *
* @{
*/
-/* Public key decoding functions */
+/* Public key decoding functions */
const char *ssh_type_to_char(int type) {
switch (type) {
case TYPE_DSS:
@@ -299,10 +301,14 @@ error:
return NULL;
}
-/** \brief Makes a PUBLIC_KEY object out of a PRIVATE_KEY object
- * \param prv the Private key
- * \returns the public key
- * \see publickey_to_string()
+/**
+ * @brief Make a public_key object out of a private_key object.
+ *
+ * @param[in] prv The private key to generate the public key.
+ *
+ * @returns The generated public key, NULL on error.
+ *
+ * @see publickey_to_string()
*/
ssh_public_key publickey_from_privatekey(ssh_private_key prv) {
ssh_public_key key = NULL;
@@ -657,10 +663,15 @@ error:
return rc;
}
-/** \brief makes a SSH String out of a PUBLIC_KEY object
- * \param key the public key
- * \returns a SSH String containing the public key
- * \see string_free()
+/**
+ * @brief Convert a public_key object into a a SSH string.
+ *
+ * @param[in] key The public key to convert.
+ *
+ * @returns An allocated SSH String containing the public key, NULL
+ * on error.
+ *
+ * @see string_free()
*/
ssh_string publickey_to_string(ssh_public_key key) {
ssh_string type = NULL;
@@ -1476,5 +1487,6 @@ ssh_string ssh_sign_session_id(ssh_session session, ssh_private_key privatekey)
return signature;
}
-/** @} */
-/* vim: set ts=2 sw=2 et cindent: */
+/* @} */
+
+/* vim: set ts=4 sw=4 et cindent: */