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