#include <stdio.h>
#include <stdint.h>
#include <stdbool.h>
#include <sys/types.h>
#include <daos_prop.h>

Data Structures
struct	daos_acl

struct	daos_ace

Macros
#define	DAOS_ACL_VERSION (1)

#define	DAOS_ACL_MAX_PRINCIPAL_LEN (255)

#define	DAOS_ACL_MAX_PRINCIPAL_BUF_LEN (DAOS_ACL_MAX_PRINCIPAL_LEN + 1)

#define	DAOS_ACL_PRINCIPAL_OWNER "OWNER@"

#define	DAOS_ACL_PRINCIPAL_OWNER_GRP "GROUP@"

#define	DAOS_ACL_PRINCIPAL_EVERYONE "EVERYONE@"

#define	DAOS_ACL_MAX_ACE_LEN (65536)

#define	DAOS_ACL_MAX_ACE_STR_LEN (DAOS_ACL_MAX_PRINCIPAL_LEN + 64)

#define	DAOS_ACL_ACCESS_ALL

#define	DAOS_ACL_FLAG_ALL

#define	DAOS_ACL_PERM_POOL_ALL

#define	DAOS_ACL_PERM_CONT_ALL

#define	DAOS_ACL_PERM_ALL

Enumerations
enum	daos_acl_principal_type { DAOS_ACL_OWNER , DAOS_ACL_USER , DAOS_ACL_OWNER_GROUP , DAOS_ACL_GROUP , DAOS_ACL_EVERYONE , NUM_DAOS_ACL_TYPES }

enum	daos_acl_access_type { DAOS_ACL_ACCESS_ALLOW = (1U << 0) , DAOS_ACL_ACCESS_AUDIT = (1U << 1) , DAOS_ACL_ACCESS_ALARM = (1U << 2) }

enum	daos_acl_flags { DAOS_ACL_FLAG_GROUP = (1U << 0) , DAOS_ACL_FLAG_POOL_INHERIT = (1U << 1) , DAOS_ACL_FLAG_ACCESS_FAIL = (1U << 2) , DAOS_ACL_FLAG_ACCESS_SUCCESS = (1U << 3) }

enum	daos_acl_perm { DAOS_ACL_PERM_READ = (1U << 0) , DAOS_ACL_PERM_WRITE = (1U << 1) , DAOS_ACL_PERM_CREATE_CONT = (1U << 2) , DAOS_ACL_PERM_DEL_CONT = (1U << 3) , DAOS_ACL_PERM_GET_PROP = (1U << 4) , DAOS_ACL_PERM_SET_PROP = (1U << 5) , DAOS_ACL_PERM_GET_ACL = (1U << 6) , DAOS_ACL_PERM_SET_ACL = (1U << 7) , DAOS_ACL_PERM_SET_OWNER = (1U << 8) }

Functions
struct daos_acl *	daos_acl_create (struct daos_ace *aces[], uint16_t num_aces)

struct daos_acl *	daos_acl_dup (struct daos_acl *acl)

void	daos_acl_free (struct daos_acl *acl)

ssize_t	daos_acl_get_size (struct daos_acl *acl)

struct daos_ace *	daos_acl_get_next_ace (struct daos_acl acl, struct daos_ace current_ace)

int	daos_acl_get_ace_for_principal (struct daos_acl acl, enum daos_acl_principal_type type, const char principal, struct daos_ace **ace)

int	daos_acl_add_ace (struct daos_acl *acl, struct daos_ace new_ace)

int	daos_acl_remove_ace (struct daos_acl *acl, enum daos_acl_principal_type type, const char principal_name)

void	daos_acl_dump (struct daos_acl *acl)

int	daos_acl_validate (struct daos_acl *acl)

struct daos_ace *	daos_ace_create (enum daos_acl_principal_type type, const char *principal_name)

void	daos_ace_free (struct daos_ace *ace)

ssize_t	daos_ace_get_size (struct daos_ace *ace)

void	daos_ace_dump (struct daos_ace *ace, uint32_t tabs)

bool	daos_ace_is_valid (struct daos_ace *ace)

bool	daos_acl_principal_is_valid (const char *name)

int	daos_acl_uid_to_principal (uid_t uid, char **name)

int	daos_acl_gid_to_principal (gid_t gid, char **name)

int	daos_acl_principal_to_uid (const char principal, uid_t uid)

int	daos_acl_principal_to_gid (const char principal, gid_t gid)

const char *	daos_ace_get_principal_str (struct daos_ace *ace)

int	daos_ace_from_str (const char str, struct daos_ace *ace)

int	daos_ace_to_str (struct daos_ace ace, char buf, size_t buf_len)

int	daos_ace_str_get_verbose (const char ace_str, char buf, size_t buf_len)

int	daos_acl_from_strs (const char ace_strs, size_t ace_nr, struct daos_acl acl)

int	daos_acl_to_strs (struct daos_acl acl, char *ace_strs, size_t ace_nr)

int	daos_acl_principal_from_str (const char principal_str, enum daos_acl_principal_type type, char **name)

int	daos_acl_to_stream (FILE stream, struct daos_acl acl, bool verbose)

Detailed Description

DAOS API methods for security and access control

Definition in file daos_security.h.

Macro Definition Documentation

◆ DAOS_ACL_ACCESS_ALL

#define DAOS_ACL_ACCESS_ALL

Value:

                 (DAOS_ACL_ACCESS_ALLOW |       \
                 DAOS_ACL_ACCESS_AUDIT |        \
                 DAOS_ACL_ACCESS_ALARM)

Mask of all valid access bits

Definition at line 101 of file daos_security.h.

◆ DAOS_ACL_FLAG_ALL

#define DAOS_ACL_FLAG_ALL

Value:

                 (DAOS_ACL_FLAG_GROUP |         \
                 DAOS_ACL_FLAG_POOL_INHERIT |       \
                 DAOS_ACL_FLAG_ACCESS_FAIL |        \
                 DAOS_ACL_FLAG_ACCESS_SUCCESS)

Mask of all valid flag bits

Definition at line 122 of file daos_security.h.

◆ DAOS_ACL_MAX_ACE_LEN

#define DAOS_ACL_MAX_ACE_LEN (65536)

Maximum length of daos_acl::dal_ace (dal_len's value).

Definition at line 49 of file daos_security.h.

◆ DAOS_ACL_MAX_ACE_STR_LEN

#define DAOS_ACL_MAX_ACE_STR_LEN (DAOS_ACL_MAX_PRINCIPAL_LEN + 64)

Maximum length of an ACE provided in colon-separated string format with four components: <access>:<flags>:<principal>:<perms>

Definition at line 55 of file daos_security.h.

◆ DAOS_ACL_MAX_PRINCIPAL_BUF_LEN

#define DAOS_ACL_MAX_PRINCIPAL_BUF_LEN (DAOS_ACL_MAX_PRINCIPAL_LEN + 1)

DAOS_ACL_MAX_PRINCIPAL_LEN including NULL terminator

Definition at line 37 of file daos_security.h.

◆ DAOS_ACL_MAX_PRINCIPAL_LEN

#define DAOS_ACL_MAX_PRINCIPAL_LEN (255)

Maximum length of the user@domain principal string, not including null terminator.

Definition at line 35 of file daos_security.h.

◆ DAOS_ACL_PERM_ALL

#define DAOS_ACL_PERM_ALL

Value:

(DAOS_ACL_PERM_POOL_ALL | \

DAOS_ACL_PERM_CONT_ALL)

DAOS_ACL_PERM_POOL_ALL

#define DAOS_ACL_PERM_POOL_ALL

Definition daos_security.h:145

DAOS_ACL_PERM_CONT_ALL

#define DAOS_ACL_PERM_CONT_ALL

Definition daos_security.h:154

Mask of all valid permission bits in DAOS

Definition at line 166 of file daos_security.h.

◆ DAOS_ACL_PERM_CONT_ALL

#define DAOS_ACL_PERM_CONT_ALL

Value:

                 (DAOS_ACL_PERM_READ |          \
                 DAOS_ACL_PERM_WRITE |          \
                 DAOS_ACL_PERM_DEL_CONT |       \
                 DAOS_ACL_PERM_GET_PROP |       \
                 DAOS_ACL_PERM_SET_PROP |       \
                 DAOS_ACL_PERM_GET_ACL |        \
                 DAOS_ACL_PERM_SET_ACL |        \
                 DAOS_ACL_PERM_SET_OWNER)

Mask of all valid permissions for DAOS containers

Definition at line 154 of file daos_security.h.

◆ DAOS_ACL_PERM_POOL_ALL

#define DAOS_ACL_PERM_POOL_ALL

Value:

                 (DAOS_ACL_PERM_READ |          \
                 DAOS_ACL_PERM_GET_PROP |       \
                 DAOS_ACL_PERM_WRITE |          \
                 DAOS_ACL_PERM_CREATE_CONT |        \
                 DAOS_ACL_PERM_DEL_CONT)

Mask of all valid permissions for DAOS pools

Definition at line 145 of file daos_security.h.

◆ DAOS_ACL_PRINCIPAL_EVERYONE

#define DAOS_ACL_PRINCIPAL_EVERYONE "EVERYONE@"

Special principal string value for everyone

Definition at line 44 of file daos_security.h.

◆ DAOS_ACL_PRINCIPAL_OWNER

#define DAOS_ACL_PRINCIPAL_OWNER "OWNER@"

Special principal string value for owner

Definition at line 40 of file daos_security.h.

◆ DAOS_ACL_PRINCIPAL_OWNER_GRP

#define DAOS_ACL_PRINCIPAL_OWNER_GRP "GROUP@"

Special principal string value for group

Definition at line 42 of file daos_security.h.

◆ DAOS_ACL_VERSION

#define DAOS_ACL_VERSION (1)

Version of the ACL structure format

Definition at line 29 of file daos_security.h.

Enumeration Type Documentation

◆ daos_acl_access_type

enum daos_acl_access_type

Bits representing access types to set permissions for

Enumerator
DAOS_ACL_ACCESS_AUDIT	allow access
DAOS_ACL_ACCESS_ALARM	log the access for review

Definition at line 92 of file daos_security.h.

◆ daos_acl_flags

enum daos_acl_flags

Bits representing access flags

Enumerator
DAOS_ACL_FLAG_GROUP	This represents a group, not a user
DAOS_ACL_FLAG_POOL_INHERIT	Containers should inherit access controls from this pool
DAOS_ACL_FLAG_ACCESS_FAIL	Audit/alarm should occur on failed access
DAOS_ACL_FLAG_ACCESS_SUCCESS	Audit/alarm should occur on successful access

Definition at line 108 of file daos_security.h.

◆ daos_acl_perm

enum daos_acl_perm

Bits representing the specific permissions that may be set

Definition at line 130 of file daos_security.h.

◆ daos_acl_principal_type

enum daos_acl_principal_type

Type of principal for the Access Control Entry. OWNER, OWNER_GROUP, and EVERYONE are special principals that do not need a principal name string.

Enumerator
DAOS_ACL_USER	Owner of the object
DAOS_ACL_OWNER_GROUP	Individual user
DAOS_ACL_GROUP	Owning group
DAOS_ACL_EVERYONE	Group
NUM_DAOS_ACL_TYPES	Anyone else Must be last

Definition at line 79 of file daos_security.h.

Function Documentation

◆ daos_ace_create()

struct daos_ace * daos_ace_create	(	enum daos_acl_principal_type	type,
		const char *	principal_name )

Allocate a new Access Control Entry with an appropriately aligned principal name, if applicable.

Only User and Group types use principal name.

Parameters

[in]	type	Type of principal for the ACE
[in]	principal_name	Principal name will be added to the end of the structure. For types that don't use it, it is ignored. OK to pass NULL.

Returns: New ACE structure with an appropriately packed principal name, length, and type set.

◆ daos_ace_dump()

void daos_ace_dump	(	struct daos_ace *	ace,
		uint32_t	tabs )

Print the Access Control Entry to stdout in a verbose human-readable format.

Parameters

ace	Access Control Entry to print
tabs	Number of tabs to indent at top level

◆ daos_ace_free()

void daos_ace_free ( struct daos_ace * ace )

Free an Access Control Entry allocated by daos_ace_alloc().

Parameters

[in] ace ACE to be freed

◆ daos_ace_from_str()

int daos_ace_from_str	(	const char *	str,
		struct daos_ace **	ace )

Convert an Access Control Entry formatted as a string to a daos_ace structure.

Parameters

[in]	str	String defining an ACE
[out]	ace	Newly allocated ACE structure

Returns: 0 Success -DER_INVAL Invalid input -DER_NOMEM Could not allocate memory

◆ daos_ace_get_principal_str()

const char * daos_ace_get_principal_str ( struct daos_ace * ace )

Get the principal name string from an Access Control Entry.

Parameters

[in] ace Access Control Entry

Returns: Either the string from the principal name field, or one of the special principal names: OWNER@, GROUP@, EVERYONE@

◆ daos_ace_get_size()

ssize_t daos_ace_get_size ( struct daos_ace * ace )

Get the length in bytes of an Access Control Entry. The entries have variable length.

Parameters

[in] ace ACE to get the size of

Returns: Size of ACE in bytes -DER_INVAL Invalid input

◆ daos_ace_is_valid()

bool daos_ace_is_valid ( struct daos_ace * ace )

Sanity check the Access Control Entry structure for valid values and internal consistency.

Parameters

ace	Access Control Entry to be checked

Returns: True if the ACE is valid, false otherwise

◆ daos_ace_str_get_verbose()

int daos_ace_str_get_verbose	(	const char *	ace_str,
		char *	buf,
		size_t	buf_len )

Convert an Access Control Entry string to a verbose string.

Parameters

[in]	ace_str	ACE string
[out]	buf	Output buffer
[in]	buf_len	Length of output buffer

Returns: 0 Success -DER_INVAL Invalid input string -DER_TRUNC Output didn't fit in buffer

◆ daos_ace_to_str()

int daos_ace_to_str	(	struct daos_ace *	ace,
		char *	buf,
		size_t	buf_len )

Convert an Access Control Entry in the form of a daos_ace structure to a compact string.

Limitation: A valid ACE with different permissions for different access types cannot be formatted as a single string, and will be rejected as invalid.

Parameters

[in]	ace	ACE structure
[out]	buf	Buffer to write the string
[out]	buf_len	Size of buffer

Returns: 0 Success -DER_INVAL Invalid input

◆ daos_acl_add_ace()

int daos_acl_add_ace	(	struct daos_acl **	acl,
		struct daos_ace *	new_ace )

Insert an Access Control Entry in the appropriate location in the ACE list. The expected order is: Owner, Users, Owner-Group, Groups, Everyone.

The ACL structure may be reallocated to make room for the new ACE. If so the old structure will be freed.

If the new ACE is an update of an existing entry, it will replace the old entry.

Parameters

[in]	acl	ACL to modify
[in]	new_ace	ACE to be added

Returns: 0 Success -DER_INVAL Invalid input -DER_NOMEM Failed to allocate required memory

◆ daos_acl_create()

struct daos_acl * daos_acl_create	(	struct daos_ace *	aces[],
		uint16_t	num_aces )

Allocate an DAOS Access Control List.

Parameters

[in]	aces	Array of pointers to ACEs to be put in the ACL.
[in]	num_aces	Number of ACEs in array

Returns: allocated daos_acl pointer, NULL if failed

◆ daos_acl_dump()

void daos_acl_dump ( struct daos_acl * acl )

Print the Access Control List to stdout in a detailed human-readable format, for debug purposes.

Parameters

acl	Access Control List to print

◆ daos_acl_dup()

struct daos_acl * daos_acl_dup ( struct daos_acl * acl )

Allocate a new copy of a DAOS Access Control List.

Parameters

[in] acl ACL structure to be copied

Returns: Newly allocated copy of the ACL, or NULL if the ACL can't be allocated

◆ daos_acl_free()

void daos_acl_free ( struct daos_acl * acl )

Free a DAOS Access Control List.

Parameters

[in] acl ACL pointer to be freed

◆ daos_acl_from_strs()

int daos_acl_from_strs	(	const char **	ace_strs,
		size_t	ace_nr,
		struct daos_acl **	acl )

Convert a list of Access Control Entries formatted as strings to a daos_acl structure.

Parameters

[in]	ace_strs	Array of strings defining ACEs
[in]	ace_nr	Length of ace_strs
[out]	acl	Newly allocated ACL structure

Returns: 0 Success -DER_INVAL Invalid input -DER_NOMEM Could not allocate memory

◆ daos_acl_get_ace_for_principal()

int daos_acl_get_ace_for_principal	(	struct daos_acl *	acl,
		enum daos_acl_principal_type	type,
		const char *	principal,
		struct daos_ace **	ace )

Search the Access Control List for an Access Control Entry for a specific principal.

Parameters

[in]	acl	ACL to search
[in]	type	Principal type to search for
[in]	principal	Principal name, if type is USER or GROUP. NULL otherwise.
[out]	ace	Pointer to matching ACE within ACL (not a copy)

Returns: 0 Success -DER_INVAL Invalid input -DER_NONEXIST Matching ACE not found

◆ daos_acl_get_next_ace()

struct daos_ace * daos_acl_get_next_ace	(	struct daos_acl *	acl,
		struct daos_ace *	current_ace )

Get the next Access Control Entry in the Access Control List, for iterating over the list.

Parameters

[in]	acl	ACL to traverse
[in]	current_ace	Current ACE, to determine the next one, or NULL for the first ACE

Returns: Pointer to the next ACE in the ACL, or NULL if at the end

◆ daos_acl_get_size()

ssize_t daos_acl_get_size ( struct daos_acl * acl )

Get the total size of the DAOS Access Control List in bytes. This includes the size of the header as well as the ACE list.

Parameters

[in] acl ACL to get the size of

Returns: Size of ACL in bytes -DER_INVAL Invalid input

◆ daos_acl_gid_to_principal()

int daos_acl_gid_to_principal	(	gid_t	gid,
		char **	name )

Convert a local gid to a properly-formatted principal name for use with the Access Control List API.

Parameters

[in]	gid	GID to convert
[out]	name	Newly allocated null-terminated string containing the formatted principal name

Returns: 0 Success -DER_INVAL Invalid input -DER_NONEXIST GID not found -DER_NOMEM Could not allocate memory

◆ daos_acl_principal_from_str()

int daos_acl_principal_from_str	(	const char *	principal_str,
		enum daos_acl_principal_type *	type,
		char **	name )

Convert a formatted principal string to an ACL principal type and name suitable for creating or looking up an Access Control Entry.

The format of the input string is:

For named user: "u:username@"
For named group: "g:groupname@"
For special types: "OWNER@", "GROUP@", or "EVERYONE@"

Parameters

[in]	principal_str	Formatted principal string
[out]	type	Type determined from the string
[out]	name	Newly-allocated name string. Caller is responsible for freeing. Result may be NULL if the principal is one of the special types.

Returns: 0 Success -DER_INVAL Invalid input -DER_NOMEM Could not allocate memory

◆ daos_acl_principal_is_valid()

bool daos_acl_principal_is_valid ( const char * name )

Sanity check that the principal is a properly-formatted name string for use in an Access Control List.

The check is not very strict. It verifies that the name is in the name@[domain] format, but does not make assumptions about legal characters in the name or verify that the principal actually exists

Parameters

name	Principal name to be validated

Returns: true if the name is properly formatted false otherwise

◆ daos_acl_principal_to_gid()

int daos_acl_principal_to_gid	(	const char *	principal,
		gid_t *	gid )

Convert the name of a group principal from an Access Control List to its corresponding local GID.

Parameters

[in]	principal	Principal name
[out]	gid	GID of the principal

Returns: 0 Success -DER_INVAL Invalid input -DER_NONEXIST Group not found -DER_NOMEM Could not allocate memory

◆ daos_acl_principal_to_uid()

int daos_acl_principal_to_uid	(	const char *	principal,
		uid_t *	uid )

Convert the name of a user principal from an Access Control List to its corresponding local UID.

Parameters

[in]	principal	Principal name
[out]	uid	UID of the principal

Returns: 0 Success -DER_INVAL Invalid input -DER_NONEXIST User not found -DER_NOMEM Could not allocate memory

◆ daos_acl_remove_ace()

int daos_acl_remove_ace	(	struct daos_acl **	acl,
		enum daos_acl_principal_type	type,
		const char *	principal_name )

Remove an Access Control Entry from the list.

When the entry is removed, the ACL is reallocated, and the old structure is freed.

Parameters

[in]	acl	Original ACL
[in]	type	Principal type of the ACE to remove
[in]	principal_name	Principal name of the ACE to remove (NULL if type isn't user/group)

Returns: 0 Success -DER_INVAL Invalid input -DER_NOMEM Failed to allocate required memory -DER_NONEXIST Requested ACE was not in the ACL

◆ daos_acl_to_stream()

int daos_acl_to_stream	(	FILE *	stream,
		struct daos_acl *	acl,
		bool	verbose )

Print the Access Control List to a stream in the ACL file format.

Parameters

[in]	stream	Open stream to which the ACL should be printed
[in]	acl	Access Control List to print
[in]	verbose	Include verbose comment for each ACE in output

Returns: 0 Success -DER_INVAL Invalid input -DER_NOMEM Could not allocate memory -DER_IO Failed to write to stream

◆ daos_acl_to_strs()

int daos_acl_to_strs	(	struct daos_acl *	acl,
		char ***	ace_strs,
		size_t *	ace_nr )

Convert an Access Control List (daos_acl) to a list of Access Control Entries formatted as strings.

Each entry in ace_strs is dynamically allocated. So is the array itself. It is the caller's responsibility to free all of them.

Parameters

[in]	acl	DAOS ACL
[out]	ace_strs	Newly allocated array of strings
[out]	ace_nr	Length of ace_strs

Returns: 0 Success -DER_INVAL Invalid input -DER_NOMEM Could not allocate memory

◆ daos_acl_uid_to_principal()

int daos_acl_uid_to_principal	(	uid_t	uid,
		char **	name )

Convert a local uid to a properly-formatted principal name for use with the Access Control List API.

Parameters

[in]	uid	UID to convert
[out]	name	Newly allocated null-terminated string containing the formatted principal name

Returns: 0 Success -DER_INVAL Invalid input -DER_NONEXIST UID not found -DER_NOMEM Could not allocate memory

◆ daos_acl_validate()

int daos_acl_validate ( struct daos_acl * acl )

Parse and sanity check the entire Access Control List for valid values and internal consistency.

Parameters

acl	Access Control List to sanity check

Returns: 0 ACL is valid -DER_INVAL ACL is not valid -DER_NOMEM Ran out of memory while checking

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ DAOS_ACL_ACCESS_ALL

◆ DAOS_ACL_FLAG_ALL

◆ DAOS_ACL_MAX_ACE_LEN

◆ DAOS_ACL_MAX_ACE_STR_LEN

◆ DAOS_ACL_MAX_PRINCIPAL_BUF_LEN

◆ DAOS_ACL_MAX_PRINCIPAL_LEN

◆ DAOS_ACL_PERM_ALL

◆ DAOS_ACL_PERM_CONT_ALL

◆ DAOS_ACL_PERM_POOL_ALL

◆ DAOS_ACL_PRINCIPAL_EVERYONE

◆ DAOS_ACL_PRINCIPAL_OWNER

◆ DAOS_ACL_PRINCIPAL_OWNER_GRP

◆ DAOS_ACL_VERSION

Enumeration Type Documentation

◆ daos_acl_access_type

◆ daos_acl_flags

◆ daos_acl_perm

◆ daos_acl_principal_type

Function Documentation

◆ daos_ace_create()

◆ daos_ace_dump()

◆ daos_ace_free()

◆ daos_ace_from_str()

◆ daos_ace_get_principal_str()

◆ daos_ace_get_size()

◆ daos_ace_is_valid()

◆ daos_ace_str_get_verbose()

◆ daos_ace_to_str()

◆ daos_acl_add_ace()

◆ daos_acl_create()

◆ daos_acl_dump()

◆ daos_acl_dup()

◆ daos_acl_free()

◆ daos_acl_from_strs()

◆ daos_acl_get_ace_for_principal()

◆ daos_acl_get_next_ace()

◆ daos_acl_get_size()

◆ daos_acl_gid_to_principal()

◆ daos_acl_principal_from_str()

◆ daos_acl_principal_is_valid()

◆ daos_acl_principal_to_gid()

◆ daos_acl_principal_to_uid()

◆ daos_acl_remove_ace()

◆ daos_acl_to_stream()

◆ daos_acl_to_strs()

◆ daos_acl_uid_to_principal()

◆ daos_acl_validate()