ports/libssh
ports/libssh
1
1
Форкнуть 0
Код Релизы 1 Активность

Fixed the documentation of auth.c

Просмотр исходного кода
Этот коммит содержится в:
Andreas Schneider 2010-04-04 14:33:08 +02:00
родитель d61a699543
Коммит e736725d35
1 изменённых файлов: 89 добавлений и 67 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

148
libssh/auth.c
Просмотреть файл

@ -41,18 +41,24 @@
#include "libssh/keys.h" #include "libssh/keys.h"
#include "libssh/auth.h" #include "libssh/auth.h"
/** \defgroup ssh_auth SSH Authentication functions /**
* \brief functions to authenticate to servers * @defgroup libssh_auth The SSH authentication functions.
* @ingroup libssh
*
* Functions to authenticate with a server.
*
* @{
*/ */
/** \addtogroup ssh_auth
* @{ */
/** /**
* @internal * @internal
* @brief ask access to the ssh-userauth service *
* @param session SSH session handle * @brief Ask access to the ssh-userauth service.
* @returns SSH_OK on success *
* @returns SSH_ERROR on error * @param[in] session The SSH session handle.
*
* @returns SSH_OK on success, SSH_ERROR on error.
*
* @bug current implementation is blocking * @bug current implementation is blocking
*/ */
static int ask_userauth(ssh_session session) { static int ask_userauth(ssh_session session) {
@ -68,8 +74,11 @@ static int ask_userauth(ssh_session session) {
return rc; return rc;
} }
/** @internal /**
* @brief handles a SSH_USERAUTH_BANNER packet * @internal
*
* @brief Handles a SSH_USERAUTH_BANNER packet.
*
* This banner should be shown to user prior to authentication * This banner should be shown to user prior to authentication
*/ */
SSH_PACKET_CALLBACK(ssh_packet_userauth_banner){ SSH_PACKET_CALLBACK(ssh_packet_userauth_banner){
@ -92,10 +101,12 @@ SSH_PACKET_CALLBACK(ssh_packet_userauth_banner){
return SSH_PACKET_USED; return SSH_PACKET_USED;
} }
/** @internal /**
* @brief handles a SSH_USERAUTH_FAILURE packet * @internal
* This handles the complete or partial authentication *
* failure. * @brief Handles a SSH_USERAUTH_FAILURE packet.
*
* This handles the complete or partial authentication failure.
*/ */
SSH_PACKET_CALLBACK(ssh_packet_userauth_failure){ SSH_PACKET_CALLBACK(ssh_packet_userauth_failure){
char *auth_methods = NULL; char *auth_methods = NULL;
@ -155,10 +166,12 @@ end:
return SSH_PACKET_USED; return SSH_PACKET_USED;
} }
/** @internal /**
* @brief handles a SSH_USERAUTH_SUCCESS packet * @internal
* It is also used to communicate the new to the *
* upper levels. * @brief Handles a SSH_USERAUTH_SUCCESS packet.
*
* It is also used to communicate the new to the upper levels.
*/ */
SSH_PACKET_CALLBACK(ssh_packet_userauth_success){ SSH_PACKET_CALLBACK(ssh_packet_userauth_success){
enter_function(); enter_function();
@ -173,11 +186,13 @@ SSH_PACKET_CALLBACK(ssh_packet_userauth_success){
return SSH_PACKET_USED; return SSH_PACKET_USED;
} }
/** @internal /**
* @brief handles a SSH_USERAUTH_PK_OK or SSH_USERAUTH_INFO_REQUEST packet * @internal
* Since the two types of packets share the same code, additional *
* work is done to understand if we are in a public key or * @brief Handles a SSH_USERAUTH_PK_OK or SSH_USERAUTH_INFO_REQUEST packet.
* keyboard-interactive context. *
* Since the two types of packets share the same code, additional work is done
* to understand if we are in a public key or keyboard-interactive context.
*/ */
SSH_PACKET_CALLBACK(ssh_packet_userauth_pk_ok){ SSH_PACKET_CALLBACK(ssh_packet_userauth_pk_ok){
enter_function(); enter_function();
@ -260,9 +275,9 @@ int ssh_userauth_list(ssh_session session, const char *username) {
/** /**
* @brief Try to authenticate through the "none" method. * @brief Try to authenticate through the "none" method.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param username Deprecated, set to NULL. * @param[in] username Deprecated, set to NULL.
* *
* @returns SSH_AUTH_ERROR: A serious error happened.\n * @returns SSH_AUTH_ERROR: A serious error happened.\n
* SSH_AUTH_DENIED: Authentication failed: use another method\n * SSH_AUTH_DENIED: Authentication failed: use another method\n
@ -350,16 +365,16 @@ error:
/** /**
* @brief Try to authenticate through public key. * @brief Try to authenticate through public key.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param username The username to authenticate. You can specify NULL if * @param[in] username The username to authenticate. You can specify NULL if
* ssh_option_set_username() has been used. You cannot try * ssh_option_set_username() has been used. You cannot try
* two different logins in a row. * two different logins in a row.
* *
* @param type The type of the public key. This value is given by * @param[in] type The type of the public key. This value is given by
* publickey_from_file(). * publickey_from_file().
* *
* @param publickey A public key returned by publickey_from_file(). * @param[in] publickey A public key returned by publickey_from_file().
* *
* @returns SSH_AUTH_ERROR: A serious error happened.\n * @returns SSH_AUTH_ERROR: A serious error happened.\n
* SSH_AUTH_DENIED: The server doesn't accept that public key as an * SSH_AUTH_DENIED: The server doesn't accept that public key as an
@ -466,16 +481,16 @@ error:
/** /**
* @brief Try to authenticate through public key. * @brief Try to authenticate through public key.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param username The username to authenticate. You can specify NULL if * @param[in] username The username to authenticate. You can specify NULL if
* ssh_option_set_username() has been used. You cannot try * ssh_option_set_username() has been used. You cannot try
* two different logins in a row. * two different logins in a row.
* *
* @param publickey A public key returned by publickey_from_file(), or NULL * @param[in] publickey A public key returned by publickey_from_file(), or NULL
* to generate automatically from privatekey. * to generate automatically from privatekey.
* *
* @param privatekey A private key returned by privatekey_from_file(). * @param[in] privatekey A private key returned by privatekey_from_file().
* *
* @returns SSH_AUTH_ERROR: A serious error happened.\n * @returns SSH_AUTH_ERROR: A serious error happened.\n
* SSH_AUTH_DENIED: Authentication failed: use another method.\n * SSH_AUTH_DENIED: Authentication failed: use another method.\n
@ -602,15 +617,15 @@ error:
/** /**
* @brief Try to authenticate through a private key file. * @brief Try to authenticate through a private key file.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param username The username to authenticate. You can specify NULL if * @param[in] username The username to authenticate. You can specify NULL if
* ssh_option_set_username() has been used. You cannot try * ssh_option_set_username() has been used. You cannot try
* two different logins in a row. * two different logins in a row.
* *
* @param filename Filename containing the private key. * @param[in] filename Filename containing the private key.
* *
* @param passphrase Passphrase to decrypt the private key. Set to null if * @param[in] passphrase Passphrase to decrypt the private key. Set to null if
* none is needed or it is unknown. * none is needed or it is unknown.
* *
* @returns SSH_AUTH_ERROR: A serious error happened.\n * @returns SSH_AUTH_ERROR: A serious error happened.\n
@ -669,13 +684,13 @@ error:
/** /**
* @brief Try to authenticate through public key with an ssh agent. * @brief Try to authenticate through public key with an ssh agent.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param username The username to authenticate. You can specify NULL if * @param[in] username The username to authenticate. You can specify NULL if
* ssh_option_set_username() has been used. You cannot try * ssh_option_set_username() has been used. You cannot try
* two different logins in a row. * two different logins in a row.
* *
* @param publickey The public key provided by the agent. * @param[in] publickey The public key provided by the agent.
* *
* @returns SSH_AUTH_ERROR: A serious error happened.\n * @returns SSH_AUTH_ERROR: A serious error happened.\n
* SSH_AUTH_DENIED: Authentication failed: use another method.\n * SSH_AUTH_DENIED: Authentication failed: use another method.\n
@ -796,13 +811,13 @@ error:
/** /**
* @brief Try to authenticate by password. * @brief Try to authenticate by password.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param username The username to authenticate. You can specify NULL if * @param[in] username The username to authenticate. You can specify NULL if
* ssh_option_set_username() has been used. You cannot try * ssh_option_set_username() has been used. You cannot try
* two different logins in a row. * two different logins in a row.
* *
* @param password The password to use. Take care to clean it after * @param[in] password The password to use. Take care to clean it after
* the authentication. * the authentication.
* *
* @returns SSH_AUTH_ERROR: A serious error happened.\n * @returns SSH_AUTH_ERROR: A serious error happened.\n
@ -909,9 +924,9 @@ error:
* It may fail, for instance it doesn't ask for a password and uses a default * It may fail, for instance it doesn't ask for a password and uses a default
* asker for passphrases (in case the private key is encrypted). * asker for passphrases (in case the private key is encrypted).
* *
* @param session The ssh session to authenticate with. * @param[in] session The ssh session to authenticate with.
* *
* @param passphrase Use this passphrase to unlock the privatekey. Use NULL * @param[in] passphrase Use this passphrase to unlock the privatekey. Use NULL
* if you don't want to use a passphrase or the user * if you don't want to use a passphrase or the user
* should be asked. * should be asked.
* *
@ -1461,13 +1476,13 @@ error:
/** /**
* @brief Try to authenticate through the "keyboard-interactive" method. * @brief Try to authenticate through the "keyboard-interactive" method.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param user The username to authenticate. You can specify NULL if * @param[in] user The username to authenticate. You can specify NULL if
* ssh_option_set_username() has been used. You cannot try * ssh_option_set_username() has been used. You cannot try
* two different logins in a row. * two different logins in a row.
* *
* @param submethods Undocumented. Set it to NULL. * @param[in] submethods Undocumented. Set it to NULL.
* *
* @returns SSH_AUTH_ERROR: A serious error happened\n * @returns SSH_AUTH_ERROR: A serious error happened\n
* SSH_AUTH_DENIED: Authentication failed : use another method\n * SSH_AUTH_DENIED: Authentication failed : use another method\n
@ -1559,7 +1574,7 @@ int ssh_userauth_kbdint(ssh_session session, const char *user,
* You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This * You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This
* function returns the questions from the server. * function returns the questions from the server.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @returns The number of prompts. * @returns The number of prompts.
*/ */
@ -1573,7 +1588,7 @@ int ssh_userauth_kbdint_getnprompts(ssh_session session) {
* You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This * You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This
* function returns the questions from the server. * function returns the questions from the server.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @returns The name of the message block. Do not free it. * @returns The name of the message block. Do not free it.
*/ */
@ -1587,7 +1602,7 @@ const char *ssh_userauth_kbdint_getname(ssh_session session) {
* You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This * You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This
* function returns the questions from the server. * function returns the questions from the server.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @returns The instruction of the message block. * @returns The instruction of the message block.
*/ */
@ -1602,11 +1617,11 @@ const char *ssh_userauth_kbdint_getinstruction(ssh_session session) {
* You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This * You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. This
* function returns the questions from the server. * function returns the questions from the server.
* *
* @param session The ssh session to use. * @param[in] session The ssh session to use.
* *
* @param i The index number of the i'th prompt. * @param[in] i The index number of the i'th prompt.
* *
* @param echo When different of NULL, it will obtain a boolean meaning * @param[in] echo When different of NULL, it will obtain a boolean meaning
* that the resulting user input should be echoed or not * that the resulting user input should be echoed or not
* (like passwords). * (like passwords).
* *
@ -1625,13 +1640,19 @@ const char *ssh_userauth_kbdint_getprompt(ssh_session session, unsigned int i,
return session->kbdint->prompts[i]; return session->kbdint->prompts[i];
} }
/** You have called ssh_userauth_kbdint() and got SSH_AUTH_INFO. this /**
* function returns the questions from the server * @brief Set the answer for a question from a message block.
* \brief set the answer for a question from a message block. *
* \param session ssh session * If you have called ssh_userauth_kbdint() and got SSH_AUTH_INFO, this
* \param i index number of the ith prompt * function returns the questions from the server.
* \param answer answer to give to server *
* \return 0 on success, < 0 on error. * @param[in] session The ssh session to use.
*
* @param[in] i index The number of the ith prompt.
*
* @param[in] answer The answer to give to the server.
*
* @return 0 on success, < 0 on error.
*/ */
int ssh_userauth_kbdint_setanswer(ssh_session session, unsigned int i, int ssh_userauth_kbdint_setanswer(ssh_session session, unsigned int i,
const char *answer) { const char *answer) {
@ -1660,5 +1681,6 @@ int ssh_userauth_kbdint_setanswer(ssh_session session, unsigned int i,
return 0; return 0;
} }
/** @} */ /* @} */
/* vim: set ts=2 sw=2 et cindent: */
/* vim: set ts=4 sw=4 et cindent: */