/*
SSSD - auth utils
Copyright (C) Simo Sorce <simo@redhat.com> 2012
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
*/
#ifndef __AUTHTOK_H__
#define __AUTHTOK_H__
#include "util/authtok-utils.h"
#include "sss_client/sss_cli.h"
/* Use sss_authtok_* accesor functions instead of struct sss_auth_token
*/
struct sss_auth_token;
/**
* @brief Returns the token type
*
* @param tok A pointer to an sss_auth_token
*
* @return A sss_authtok_type (empty, password, ...)
*/
/**
* @brief Returns the token size
*
* @param tok A pointer to an sss_auth_token
*
* @return The current size of the token payload
*/
/**
* @brief Get the data buffer
*
* @param tok A pointer to an sss_auth_token
*
* @return A pointer to the token payload
*/
/**
* @brief Returns a const string if the auth token is of type
SSS_AUTHTOK_TYPE_PASSWORD, otherwise it returns an error
*
* @param tok A pointer to an sss_auth_token
* @param pwd A pointer to a const char *, that will point to a null
* terminated string
* @param len The length of the password string
*
* @return EOK on success
* ENOENT if the token is empty
* EACCESS if the token is not a password token
*/
/**
* @brief Set a password into a an auth token, replacing any previous data
*
* @param tok A pointer to a sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
* @param password A string
* @param len The length of the string or, if 0 is passed,
* then strlen(password) will be used internally.
*
* @return EOK on success
* ENOMEM on error
*/
/**
* @brief Returns a const string if the auth token is of type
SSS_AUTHTOK_TYPE_CCFILE, otherwise it returns an error
*
* @param tok A pointer to an sss_auth_token
* @param ccfile A pointer to a const char *, that will point to a null
* terminated string, also used as a memory context use to allocate the internal data
* @param len The length of the string
*
* @return EOK on success
* ENOENT if the token is empty
* EACCESS if the token is not a password token
*/
/**
* @brief Set a cc file name into a an auth token, replacing any previous data
*
* @param tok A pointer to a sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
* @param ccfile A null terminated string
* @param len The length of the string
*
* @return EOK on success
* ENOMEM on error
*/
/**
* @brief Resets an auth token to the empty status
*
* @param tok A pointer to a sss_auth_token structure to reset
*
* NOTE: This function uses safezero() on the payload if the type
* is SSS_AUTHTOK_TYPE_PASSWORD
*/
/**
* @brief Set an auth token by type, replacing any previous data
*
* @param tok A pointer to a sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
* @param type A valid authtok type
* @param data A data pointer
* @param len The length of the data
*
* @return EOK on success
* ENOMEM or EINVAL on error
*/
enum sss_authtok_type type,
/**
* @brief Copy an auth token from source to destination
*
* @param src The source auth token
* @param dst The destination auth token, also used as a memory context
* to allocate dst internal data.
*
* @return EOK on success
* ENOMEM on error
*/
struct sss_auth_token *dst);
/**
* @brief Uses safezero to wipe the password from memory if the
* authtoken contains a password, otherwise does nothing.
*
* @param tok A pointer to a sss_auth_token structure to change
*
* NOTE: This function should only be used in destructors or similar
* functions where freing the actual string is unsafe and where it can
* be guaranteed that the auth token will not be used anymore.
* Use sss_authtok_set_empty() in normal circumstances.
*/
/**
* @brief Create new empty struct sss_auth_token.
*
* @param mem_ctx A memory context use to allocate the internal data
* @return A pointer to new empty struct sss_auth_token
* NULL in case of failure
*
* NOTE: This function is the only way, how to create new empty
* struct sss_auth_token.
*/
/**
* @brief Set authtoken with 2FA data
*
* @param tok A pointer to a sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
* @param[in] fa1 First authentication factor, null terminated
* @param[in] fa1_len Length of the first authentication factor, if 0
* strlen() will be called internally
* @param[in] fa2 Second authentication factor, null terminated
* @param[in] fa2_len Length of the second authentication factor, if 0
* strlen() will be called internally
*
* @return EOK on success
* ENOMEM if memory allocation failed
* EINVAL if input data is not consistent
*/
/**
* @brief Get 2FA factors from authtoken
*
* @param tok A pointer to a sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
* @param[out] fa1 A pointer to a const char *, that will point to a
* null terminated string holding the first
* authentication factor, may not be modified or freed
* @param[out] fa1_len Length of the first authentication factor
* @param[out] fa2 A pointer to a const char *, that will point to a
* null terminated string holding the second
* authentication factor, may not be modified or freed
* @param[out] fa2_len Length of the second authentication factor
*
* @return EOK on success
* ENOMEM if memory allocation failed
* EINVAL if input data is not consistent
* ENOENT if the token is empty
* EACCESS if the token is not a 2FA token
*/
/**
* @brief Set a Smart Card pin into a an auth token, replacing any previous data
*
* @param tok A pointer to a sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
* @param pin A string
* @param len The length of the string or, if 0 is passed,
* then strlen(password) will be used internally.
*
* @return EOK on success
* ENOMEM on error
*/
/**
* @brief Returns a Smart Card pin as const string if the auth token is of
* type SSS_AUTHTOK_TYPE_SC_PIN, otherwise it returns an error
*
* @param tok A pointer to an sss_auth_token
* @param pin A pointer to a const char *, that will point to a null
* terminated string
* @param len The length of the pin string
*
* @return EOK on success
* ENOENT if the token is empty
* EACCESS if the token is not a Smart Card pin token
*/
/**
* @brief Sets an auth token to type SSS_AUTHTOK_TYPE_SC_KEYPAD, replacing any
* previous data
*
* @param tok A pointer to a sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
*/
#endif /* __AUTHTOK_H__ */