summaryrefslogtreecommitdiffstats
path: root/libsubid/subid.h
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--libsubid/subid.h163
-rw-r--r--libsubid/subid.h.in163
2 files changed, 326 insertions, 0 deletions
diff --git a/libsubid/subid.h b/libsubid/subid.h
new file mode 100644
index 0000000..d13ee84
--- /dev/null
+++ b/libsubid/subid.h
@@ -0,0 +1,163 @@
+#include <sys/types.h>
+#include <stdio.h>
+#include <stdbool.h>
+
+#ifndef SUBID_RANGE_DEFINED
+#define SUBID_RANGE_DEFINED 1
+#define SUBID_ABI_VERSION 4.0.0
+#define SUBID_ABI_MAJOR 4
+#define SUBID_ABI_MINOR 0
+#define SUBID_ABI_MICRO 0
+
+/* 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
+};
+
+enum subid_status {
+ SUBID_STATUS_SUCCESS = 0,
+ SUBID_STATUS_UNKNOWN_USER = 1,
+ SUBID_STATUS_ERROR_CONN = 2,
+ SUBID_STATUS_ERROR = 3,
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * 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);
+
+#ifdef __cplusplus
+}
+#endif
+
+#define SUBID_NFIELDS 3
+#endif
diff --git a/libsubid/subid.h.in b/libsubid/subid.h.in
new file mode 100644
index 0000000..79744ed
--- /dev/null
+++ b/libsubid/subid.h.in
@@ -0,0 +1,163 @@
+#include <sys/types.h>
+#include <stdio.h>
+#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
+};
+
+enum subid_status {
+ SUBID_STATUS_SUCCESS = 0,
+ SUBID_STATUS_UNKNOWN_USER = 1,
+ SUBID_STATUS_ERROR_CONN = 2,
+ SUBID_STATUS_ERROR = 3,
+};
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*
+ * 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);
+
+#ifdef __cplusplus
+}
+#endif
+
+#define SUBID_NFIELDS 3
+#endif