shadow/libsubid/subid.h.in

156 lines
4.8 KiB
C
Raw Normal View History

#include <sys/types.h>
#include <stdio.h>
subids: support nsswitch Closes #154 When starting any operation to do with subuid delegation, check nsswitch for a module to use. If none is specified, then use the traditional /etc/subuid and /etc/subgid files. Currently only one module is supported, and there is no fallback to the files on errors. Several possibilities could be considered: 1. in case of connection error, fall back to files 2. in case of unknown user, also fall back to files etc... When non-files nss module is used, functions to edit the range are not supported. It may make sense to support it, but it also may make sense to require another tool to be used. libsubordinateio also uses the nss_ helpers. This is how for instance lxc could easily be converted to supporting nsswitch. Add a set of test cases, including a dummy libsubid_zzz module. This hardcodes values such that: 'ubuntu' gets 200000 - 300000 'user1' gets 100000 - 165536 'error' emulates an nss module error 'unknown' emulates a user unknown to the nss module 'conn' emulates a connection error ot the nss module Changes to libsubid: Change the list_owner_ranges api: return a count instead of making the array null terminated. This is a breaking change, so bump the libsubid abi major number. Rename free_subuid_range and free_subgid_range to ungrant_subuid_range, because otherwise it's confusing with free_subid_ranges which frees memory. Run libsubid tests in jenkins Switch argument order in find_subid_owners Move the db locking into subordinateio.c Signed-off-by: Serge Hallyn <serge@hallyn.com>
2021-02-01 05:08:20 +05:30
#include <stdbool.h>
#ifndef SUBID_RANGE_DEFINED
#define SUBID_RANGE_DEFINED 1
#define SUBID_ABI_VERSION @LIBSUBID_ABI_MAJOR@.@LIBSUBID_ABI_MINOR@.@LIBSUBID_ABI_MICRO@
#define SUBID_ABI_MAJOR @LIBSUBID_ABI_MAJOR@
#define SUBID_ABI_MINOR @LIBSUBID_ABI_MINOR@
#define SUBID_ABI_MICRO @LIBSUBID_ABI_MICRO@
/* subid_range is just a starting point and size of a range */
struct subid_range {
unsigned long start;
unsigned long count;
};
/* subordinage_range is a subid_range plus an owner, representing
* a range in /etc/subuid or /etc/subgid */
struct subordinate_range {
const char *owner;
unsigned long start;
unsigned long count;
};
enum subid_type {
ID_TYPE_UID = 1,
ID_TYPE_GID = 2
};
subids: support nsswitch Closes #154 When starting any operation to do with subuid delegation, check nsswitch for a module to use. If none is specified, then use the traditional /etc/subuid and /etc/subgid files. Currently only one module is supported, and there is no fallback to the files on errors. Several possibilities could be considered: 1. in case of connection error, fall back to files 2. in case of unknown user, also fall back to files etc... When non-files nss module is used, functions to edit the range are not supported. It may make sense to support it, but it also may make sense to require another tool to be used. libsubordinateio also uses the nss_ helpers. This is how for instance lxc could easily be converted to supporting nsswitch. Add a set of test cases, including a dummy libsubid_zzz module. This hardcodes values such that: 'ubuntu' gets 200000 - 300000 'user1' gets 100000 - 165536 'error' emulates an nss module error 'unknown' emulates a user unknown to the nss module 'conn' emulates a connection error ot the nss module Changes to libsubid: Change the list_owner_ranges api: return a count instead of making the array null terminated. This is a breaking change, so bump the libsubid abi major number. Rename free_subuid_range and free_subgid_range to ungrant_subuid_range, because otherwise it's confusing with free_subid_ranges which frees memory. Run libsubid tests in jenkins Switch argument order in find_subid_owners Move the db locking into subordinateio.c Signed-off-by: Serge Hallyn <serge@hallyn.com>
2021-02-01 05:08:20 +05:30
enum subid_status {
SUBID_STATUS_SUCCESS = 0,
SUBID_STATUS_UNKNOWN_USER = 1,
SUBID_STATUS_ERROR_CONN = 2,
SUBID_STATUS_ERROR = 3,
};
/*
* subid_init: initialize libsubid
*
* @progname: Name to display as program. If NULL, then "(libsubid)" will be
* shown in error messages.
* @logfd: Open file pointer to pass error messages to. If NULL, then
* /dev/null will be opened and messages will be sent there. The
* default if libsubid_init() is not called is stderr (2).
*
* This function does not need to be called. If not called, then the defaults
* will be used.
*
* Returns false if an error occurred.
*/
bool subid_init(const char *progname, FILE *logfd);
/*
* subid_get_uid_ranges: return a list of UID ranges for a user
*
* @owner: username being queried
* @ranges: a pointer to an array of subid_range structs in which the result
* will be returned.
*
* The caller must free(ranges) when done.
*
* returns: number of ranges found, ir < 0 on error.
*/
int subid_get_uid_ranges(const char *owner, struct subid_range **ranges);
/*
* subid_get_gid_ranges: return a list of GID ranges for a user
*
* @owner: username being queried
* @ranges: a pointer to an array of subid_range structs in which the result
* will be returned.
*
* The caller must free(ranges) when done.
*
* returns: number of ranges found, ir < 0 on error.
*/
int subid_get_gid_ranges(const char *owner, struct subid_range **ranges);
/*
* subid_get_uid_owners: return a list of uids to which the given uid has been
* delegated.
*
* @uid: The subuid being queried
* @owners: a pointer to an array of uids into which the results are placed.
* The returned array must be freed by the caller.
*
* Returns the number of uids returned, or < 0 on error.
*/
int subid_get_uid_owners(uid_t uid, uid_t **owner);
/*
* subid_get_gid_owners: return a list of uids to which the given gid has been
* delegated.
*
* @uid: The subgid being queried
* @owners: a pointer to an array of uids into which the results are placed.
* The returned array must be freed by the caller.
*
* Returns the number of uids returned, or < 0 on error.
*/
int subid_get_gid_owners(gid_t gid, uid_t **owner);
/*
* subid_grant_uid_range: assign a subuid range to a user
*
* @range: pointer to a struct subordinate_range detailing the UID range
* to allocate. ->owner must be the username, and ->count must be
* filled in. ->start is ignored, and will contain the start
* of the newly allocated range, upon success.
*
* Returns true if the delegation succeeded, false otherwise. If true,
* then the range from (range->start, range->start + range->count) will
* be delegated to range->owner.
*/
bool subid_grant_uid_range(struct subordinate_range *range, bool reuse);
/*
* subid_grant_gid_range: assign a subgid range to a user
*
* @range: pointer to a struct subordinate_range detailing the GID range
* to allocate. ->owner must be the username, and ->count must be
* filled in. ->start is ignored, and will contain the start
* of the newly allocated range, upon success.
*
* Returns true if the delegation succeeded, false otherwise. If true,
* then the range from (range->start, range->start + range->count) will
* be delegated to range->owner.
*/
bool subid_grant_gid_range(struct subordinate_range *range, bool reuse);
/*
* subid_ungrant_uid_range: remove a subuid allocation.
*
* @range: pointer to a struct subordinate_range detailing the UID allocation
* to remove.
*
* Returns true if successful, false if it failed, for instance if the
* delegation did not exist.
*/
bool subid_ungrant_uid_range(struct subordinate_range *range);
/*
* subid_ungrant_gid_range: remove a subgid allocation.
*
* @range: pointer to a struct subordinate_range detailing the GID allocation
* to remove.
*
* Returns true if successful, false if it failed, for instance if the
* delegation did not exist.
*/
bool subid_ungrant_gid_range(struct subordinate_range *range);
#define SUBID_NFIELDS 3
#endif