/*
SSSD - auth utils
Copyright (C) Simo Sorce <simo@redhat.com> 2012
This program is free software; you can redistribute it and/or modify
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/util.h"
#include "util/authtok-utils.h"
#include "sss_client/sss_cli.h"
/* Use sss_authtok_* accessor 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 An sss_authtok_type (empty, password, ...)
*/
enum sss_authtok_type sss_authtok_get_type(struct sss_auth_token *tok);
/**
* @brief Returns the token size
*
* @param tok A pointer to an sss_auth_token
*
* @return The current size of the token payload
*/
size_t sss_authtok_get_size(struct sss_auth_token *tok);
/**
* @brief Get the data buffer
*
* @param tok A pointer to an sss_auth_token
*
* @return A pointer to the token payload
*/
uint8_t *sss_authtok_get_data(struct sss_auth_token *tok);
/**
* @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
*/
errno_t sss_authtok_get_password(struct sss_auth_token *tok,
const char **pwd, size_t *len);
/**
* @brief Set a password into an auth token, replacing any previous data
*
* @param tok A pointer to an 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
*/
errno_t sss_authtok_set_password(struct sss_auth_token *tok,
const char *password, size_t len);
/**
* @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
*/
errno_t sss_authtok_get_ccfile(struct sss_auth_token *tok,
const char **ccfile, size_t *len);
/**
* @brief Set a cc file name into an auth token, replacing any previous data
*
* @param tok A pointer to an 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
*/
errno_t sss_authtok_set_ccfile(struct sss_auth_token *tok,
const char *ccfile, size_t len);
/**
* @brief Resets an auth token to the empty status
*
* @param tok A pointer to an sss_auth_token structure to reset
*
* NOTE: This function uses safezero() on the payload if the type
* is SSS_AUTHTOK_TYPE_PASSWORD
*/
void sss_authtok_set_empty(struct sss_auth_token *tok);
/**
* @brief Set an auth token by type, replacing any previous data
*
* @param tok A pointer to an 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
*/
errno_t sss_authtok_set(struct sss_auth_token *tok,
enum sss_authtok_type type,
const uint8_t *data, size_t len);
/**
* @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
*/
errno_t sss_authtok_copy(struct sss_auth_token *src,
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 an sss_auth_token structure to change
*
* NOTE: This function should only be used in destructors or similar
* functions where freeing 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.
*/
void sss_authtok_wipe_password(struct sss_auth_token *tok);
/**
* @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.
*/
struct sss_auth_token *sss_authtok_new(TALLOC_CTX *mem_ctx);
/**
* @brief Set authtoken with 2FA data
*
* @param tok A pointer to an 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
*/
errno_t sss_authtok_set_2fa(struct sss_auth_token *tok,
const char *fa1, size_t fa1_len,
const char *fa2, size_t fa2_len);
/**
* @brief Get 2FA factors from authtoken
*
* @param tok A pointer to an 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
*/
errno_t sss_authtok_get_2fa(struct sss_auth_token *tok,
const char **fa1, size_t *fa1_len,
const char **fa2, size_t *fa2_len);
/**
* @brief Set a Smart Card PIN into an auth token, replacing any previous data
*
* @param tok A pointer to an 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
*/
errno_t sss_authtok_set_sc_pin(struct sss_auth_token *tok, const char *pin,
size_t len);
/**
* @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
*/
errno_t sss_authtok_get_sc_pin(struct sss_auth_token *tok, const char **pin,
size_t *len);
/**
* @brief Sets an auth token to type SSS_AUTHTOK_TYPE_SC_KEYPAD, replacing any
* previous data
*
* @param tok A pointer to an sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
*/
void sss_authtok_set_sc_keypad(struct sss_auth_token *tok);
/**
* @brief Set complete Smart Card authentication blob including PKCS#11 token
* name, module name and key id.
*
* @param tok A pointer to an sss_auth_token
* @param type Authentication token type, may be
* SSS_AUTHTOK_TYPE_SC_PIN or SSS_AUTHTOK_TYPE_SC_KEYPAD
* @param pin A pointer to a const char *, that will point to a null
* terminated string containing the PIN
* @param pin_len The length of the pin string, if set to 0 it will be
* calculated
* @param token_name A pointer to a const char *, that will point to a null
* terminated string containing the PKCS#11 token name
* @param token_name_len The length of the token name string, if set to 0 it
* will be calculated
* @param module_name A pointer to a const char *, that will point to a null
* terminated string containing the PKCS#11 module name
* @param module_name_len The length of the module name string, if set to 0 it
* will be calculated
* @param key_id A pointer to a const char *, that will point to a null
* terminated string containing the PKCS#11 key id
* @param key_id_len The length of the key id string, if set to 0 it will be
* calculated
*
* @return EOK on success
* EINVAL unexpected or inval input
* ENOMEM memory allocation error
*/
errno_t sss_authtok_set_sc(struct sss_auth_token *tok,
enum sss_authtok_type type,
const char *pin, size_t pin_len,
const char *token_name, size_t token_name_len,
const char *module_name, size_t module_name_len,
const char *key_id, size_t key_id_len);
/**
* @brief Set a Smart Card authentication data, replacing any previous data
*
* @param tok A pointer to an sss_auth_token structure to change, also
* used as a memory context to allocate the internal data.
* @param data Smart Card authentication data blob
* @param len The length of the blob
*
* @return EOK on success
* ENOMEM on error
*/
errno_t sss_authtok_set_sc_from_blob(struct sss_auth_token *tok,
const uint8_t *data,
size_t len);
/**
* @brief Get complete Smart Card authtoken data
*
* @param tok A pointer to an sss_auth_token structure
* @param[out] _pin A pointer to a const char *, that will point to
* a null terminated string holding the PIN,
* may not be modified or freed
* @param[out] _pin__len Length of the PIN
* @param[out] _token_name A pointer to a const char *, that will point to
* a null terminated string holding the PKCS#11
* token name, may not be modified or freed
* @param[out] _token_name_len Length of the PKCS#11 token name
* @param[out] _module_name A pointer to a const char *, that will point to
* a null terminated string holding the PKCS#11
* module name, may not be modified or freed
* @param[out] _module_name_len Length of the PKCS#11 module name
* @param[out] _key_id A pointer to a const char *, that will point to
* a null terminated string holding the PKCS#11
* key id, may not be modified or freed
* @param[out] _key_id_len Length of the PKCS#11 key id
*
* Any of the output pointers may be NULL if the caller does not need the
* specific item.
*
* @return EOK on success
* EFAULT missing token
* EINVAL if input data is not consistent
* ENOENT if the token is empty
* EACCESS if the token is not a Smart Card token
*/
errno_t sss_authtok_get_sc(struct sss_auth_token *tok,
const char **_pin, size_t *_pin_len,
const char **_token_name, size_t *_token_name_len,
const char **_module_name, size_t *_module_name_len,
const char **_key_id, size_t *_key_id_len);
#endif /* __AUTHTOK_H__ */