sss_idmap.h revision c51a204a40b8f85f7f525edb3e24520916d8b9c7
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/*
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller SSSD
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller ID-mapping library
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller Authors:
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller Sumit Bose <sbose@redhat.com>
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller Copyright (C) 2012 Red Hat
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller This program is free software; you can redistribute it and/or modify
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller it under the terms of the GNU General Public License as published by
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller the Free Software Foundation; either version 3 of the License, or
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller (at your option) any later version.
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller This program is distributed in the hope that it will be useful,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller but WITHOUT ANY WARRANTY; without even the implied warranty of
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller GNU General Public License for more details.
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller You should have received a copy of the GNU General Public License
f469cad18932786e1db610d6134f90b9002181c4jenkins along with this program. If not, see <http://www.gnu.org/licenses/>.
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller*/
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller#ifndef SSS_IDMAP_H_
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller#define SSS_IDMAP_H_
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller#include <stdlib.h>
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller#include <stdint.h>
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller#include <stdbool.h>
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller#define DOM_SID_PREFIX "S-1-5-21-"
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller#define DOM_SID_PREFIX_LEN (sizeof(DOM_SID_PREFIX) - 1)
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @defgroup sss_idmap Map Unix UIDs and GIDs to SIDs and back
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * Libsss_idmap provides a mechanism to translate a SID to a UNIX UID or GID
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * or the other way round.
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @{
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * Error codes used by libsss_idmap
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millerenum idmap_error_code {
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller /** Success */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_SUCCESS = 0,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
100c3de960445a33612602ff02a07eef71963486Phill Cunnington /** Function is not yet implemented */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_NOT_IMPLEMENTED,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
ea6f154d1f7fdfaccfa3a5e7846c5fe5f63b1a0fBrendan Miller /** General error */
ea6f154d1f7fdfaccfa3a5e7846c5fe5f63b1a0fBrendan Miller IDMAP_ERROR,
ea6f154d1f7fdfaccfa3a5e7846c5fe5f63b1a0fBrendan Miller
ea6f154d1f7fdfaccfa3a5e7846c5fe5f63b1a0fBrendan Miller /** Ran out of memory during processing */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_OUT_OF_MEMORY,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller /** No domain added */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_NO_DOMAIN,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller /** The provided idmap context is invalid */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_CONTEXT_INVALID,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller /** The provided SID is invalid */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_SID_INVALID,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller /** The provided SID was not found */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_SID_UNKNOWN,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller /** The provided UID or GID could not be mapped */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller IDMAP_NO_RANGE
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller};
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * Typedef for memory allocation functions
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millertypedef void *(idmap_alloc_func)(size_t size, void *pvt);
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millertypedef void (idmap_free_func)(void *ptr, void *pvt);
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * Structure for id ranges
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * FIXME: this struct might change when it is clear how ranges are handled on
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * the server side
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millerstruct sss_idmap_range {
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller uint32_t min;
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller uint32_t max;
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller};
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * Opaque type for SIDs
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millerstruct sss_dom_sid;
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * Opaque type for the idmap context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millerstruct sss_idmap_ctx;
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @brief Initialize idmap context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller *
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] alloc_func Function to allocate memory for the context, if
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * NULL malloc() id used
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] alloc_pvt Private data for allocation routine
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] free_func Function to free the memory the context, if
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * NULL free() id used
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[out] ctx idmap context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller *
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @return
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * - #IDMAP_OUT_OF_MEMORY: Insufficient memory to create the context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millerenum idmap_error_code sss_idmap_init(idmap_alloc_func *alloc_func,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller void *alloc_pvt,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller idmap_free_func *free_func,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller struct sss_idmap_ctx **ctx);
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @brief Add a domain to the idmap context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller *
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] ctx Idmap context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] domain_name Zero-terminated string with the domain name
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] domain_sid Zero-terminated string representation of the domain
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * SID (S-1-15-.....)
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] range TBD Some information about the id ranges of this
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * domain
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller *
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @return
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * - #IDMAP_OUT_OF_MEMORY: Insufficient memory to store the data in the idmap
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * - #IDMAP_SID_INVALID: Invalid SID provided
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * - #IDMAP_NO_DOMAIN: No domain domain name given
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller */
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Millerenum idmap_error_code sss_idmap_add_domain(struct sss_idmap_ctx *ctx,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller const char *domain_name,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller const char *domain_sid,
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller struct sss_idmap_range *range);
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller/**
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @brief Translate SID to a unix UID or GID
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller *
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] ctx Idmap context
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[in] sid Zero-terminated string representation of the SID
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller * @param[out] id Returned unix UID or GID
f9823ca3a77d02abd1efc634417380dbb820fc58Brendan Miller *
* @return
* - #IDMAP_NO_DOMAIN: No domains are added to the idmap context
* - #IDMAP_SID_INVALID: Invalid SID provided
* - #IDMAP_SID_UNKNOWN: SID cannot be found in the domains added to the
* idmap context
*/
enum idmap_error_code sss_idmap_sid_to_unix(struct sss_idmap_ctx *ctx,
const char *sid,
uint32_t *id);
/**
* @brief Translate a SID stucture to a unix UID or GID
*
* @param[in] ctx Idmap context
* @param[in] dom_sid SID structure
* @param[out] id Returned unix UID or GID
*
* @return
* - #IDMAP_NO_DOMAIN: No domains are added to the idmap context
* - #IDMAP_SID_INVALID: Invalid SID provided
* - #IDMAP_SID_UNKNOWN: SID cannot be found in the domains added to the
* idmap context
*/
enum idmap_error_code sss_idmap_dom_sid_to_unix(struct sss_idmap_ctx *ctx,
struct sss_dom_sid *dom_sid,
uint32_t *id);
/**
* @brief Translate a binary SID to a unix UID or GID
*
* @param[in] ctx Idmap context
* @param[in] bin_sid Array with the binary SID
* @param[in] length Size of the array containing the binary SID
* @param[out] id Returned unix UID or GID
*
* @return
* - #IDMAP_NO_DOMAIN: No domains are added to the idmap context
* - #IDMAP_SID_INVALID: Invalid SID provided
* - #IDMAP_SID_UNKNOWN: SID cannot be found in the domains added to the
* idmap context
*/
enum idmap_error_code sss_idmap_bin_sid_to_unix(struct sss_idmap_ctx *ctx,
uint8_t *bin_sid,
size_t length,
uint32_t *id);
/**
* @brief Translate unix UID or GID to a SID
*
* @param[in] ctx Idmap context
* @param[in] id unix UID or GID
* @param[out] sid Zero-terminated string representation of the SID, must be
* freed if not needed anymore
*
* @return
* - #IDMAP_NO_DOMAIN: No domains are added to the idmap context
* - #IDMAP_NO_RANGE: The provided ID cannot be found in the domains added
* to the idmap context
*/
enum idmap_error_code sss_idmap_unix_to_sid(struct sss_idmap_ctx *ctx,
uint32_t id,
char **sid);
/**
* @brief Translate unix UID or GID to a SID structure
*
* @param[in] ctx Idmap context
* @param[in] id unix UID or GID
* @param[out] dom_sid SID structure, must be freed if not needed anymore
*
* @return
* - #IDMAP_NO_DOMAIN: No domains are added to the idmap context
* - #IDMAP_NO_RANGE: The provided ID cannot be found in the domains added
* to the idmap context
*/
enum idmap_error_code sss_idmap_unix_to_dom_sid(struct sss_idmap_ctx *ctx,
uint32_t id,
struct sss_dom_sid **dom_sid);
/**
* @brief Translate unix UID or GID to a binary SID
*
* @param[in] ctx Idmap context
* @param[in] id unix UID or GID
* @param[out] bin_sid Array with the binary SID,
* must be freed if not needed anymore
* @param[out] length size of the array containing the binary SID
*
* @return
* - #IDMAP_NO_DOMAIN: No domains are added to the idmap context
* - #IDMAP_NO_RANGE: The provided ID cannot be found in the domains added
* to the idmap context
*/
enum idmap_error_code sss_idmap_unix_to_bin_sid(struct sss_idmap_ctx *ctx,
uint32_t id,
uint8_t **bin_sid,
size_t *length);
/**
* @brief Free all the allocated memory of the idmap context
*
* @param[in] ctx Idmap context
*
* @return
* - #IDMAP_CONTEXT_INVALID: Provided context is invalid
*/
enum idmap_error_code sss_idmap_free(struct sss_idmap_ctx *ctx);
/**
* @brief Translate error code to a string
*
* @param[in] err Idmap error code
*
* @return
* - Error description as a zero-terminated string
*/
const char *idmap_error_string(enum idmap_error_code err);
/**
* @brief Check if given string can be used as domain SID
*
* @param[in] str String to check
*
* @return
* - true: String can be used as domain SID
* - false: String can not be used as domain SID
*/
bool is_domain_sid(const char *str);
/**
* @brief Convert binary SID to SID structure
*
* @param[in] ctx Idmap context
* @param[in] bin_sid Array with the binary SID
* @param[in] length Size of the array containing the binary SID
* @param[out] dom_sid SID structure,
* must be freed if not needed anymore
*
* @return
* - #IDMAP_SID_INVALID: Given SID is invalid
* - #IDMAP_OUT_OF_MEMORY: Failed to allocate memory for the result
*/
enum idmap_error_code sss_idmap_bin_sid_to_dom_sid(struct sss_idmap_ctx *ctx,
const uint8_t *bin_sid,
size_t length,
struct sss_dom_sid **dom_sid);
/**
* @brief Convert binary SID to SID string
*
* @param[in] ctx Idmap context
* @param[in] bin_sid Array with the binary SID
* @param[in] length Size of the array containing the binary SID
* @param[out] sid Zero-terminated string representation of the SID,
* must be freed if not needed anymore
*
* @return
* - #IDMAP_SID_INVALID: Given SID is invalid
* - #IDMAP_OUT_OF_MEMORY: Failed to allocate memory for the result
*/
enum idmap_error_code sss_idmap_bin_sid_to_sid(struct sss_idmap_ctx *ctx,
const uint8_t *bin_sid,
size_t length,
char **sid);
/**
* @brief Convert SID structure to binary SID
*
* @param[in] ctx Idmap context
* @param[in] dom_sid SID structure
* @param[out] bin_sid Array with the binary SID,
* must be freed if not needed anymore
* @param[out] length Size of the array containing the binary SID
*
* @return
* - #IDMAP_SID_INVALID: Given SID is invalid
* - #IDMAP_OUT_OF_MEMORY: Failed to allocate memory for the result
*/
enum idmap_error_code sss_idmap_dom_sid_to_bin_sid(struct sss_idmap_ctx *ctx,
struct sss_dom_sid *dom_sid,
uint8_t **bin_sid,
size_t *length);
/**
* @brief Convert SID string to binary SID
*
* @param[in] ctx Idmap context
* @param[in] sid Zero-terminated string representation of the SID
* @param[out] bin_sid Array with the binary SID,
* must be freed if not needed anymore
* @param[out] length Size of the array containing the binary SID
*
* @return
* - #IDMAP_SID_INVALID: Given SID is invalid
* - #IDMAP_OUT_OF_MEMORY: Failed to allocate memory for the result
*/
enum idmap_error_code sss_idmap_sid_to_bin_sid(struct sss_idmap_ctx *ctx,
const char *sid,
uint8_t **bin_sid,
size_t *length);
/**
* @brief Convert SID structure to SID string
*
* @param[in] ctx Idmap context
* @param[in] dom_sid SID structure
* @param[out] sid Zero-terminated string representation of the SID,
* must be freed if not needed anymore
*
* @return
* - #IDMAP_SID_INVALID: Given SID is invalid
* - #IDMAP_OUT_OF_MEMORY: Failed to allocate memory for the result
*/
enum idmap_error_code sss_idmap_dom_sid_to_sid(struct sss_idmap_ctx *ctx,
struct sss_dom_sid *dom_sid,
char **sid);
/**
* @brief Convert SID string to SID structure
*
* @param[in] ctx Idmap context
* @param[in] sid Zero-terminated string representation of the SID
* @param[out] dom_sid SID structure,
* must be freed if not needed anymore
*
* @return
* - #IDMAP_SID_INVALID: Given SID is invalid
* - #IDMAP_OUT_OF_MEMORY: Failed to allocate memory for the result
*/
enum idmap_error_code sss_idmap_sid_to_dom_sid(struct sss_idmap_ctx *ctx,
const char *sid,
struct sss_dom_sid **dom_sid);
/**
* @}
*/
#endif /* SSS_IDMAP_H_ */