DAOS API: src/include/daos_security.h File Reference

| DAOS API (v2.1 - dev)

Loading...
Searching...
No Matches
daos_security.h File Reference
`#include <stdio.h>`
`#include <stdint.h>`
`#include <stdbool.h>`
`#include <sys/types.h>`
`#include <daos_prop.h>`

Go to the source code of this file.

## 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)
DAOS_ACL_ACCESS_AUDIT
@ DAOS_ACL_ACCESS_AUDIT
Definition daos_security.h:94
DAOS_ACL_ACCESS_ALARM
@ DAOS_ACL_ACCESS_ALARM
Definition daos_security.h:95

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)
DAOS_ACL_FLAG_ACCESS_SUCCESS
@ DAOS_ACL_FLAG_ACCESS_SUCCESS
Definition daos_security.h:116
DAOS_ACL_FLAG_POOL_INHERIT
@ DAOS_ACL_FLAG_POOL_INHERIT
Definition daos_security.h:112
DAOS_ACL_FLAG_GROUP
@ DAOS_ACL_FLAG_GROUP
Definition daos_security.h:110
DAOS_ACL_FLAG_ACCESS_FAIL
@ DAOS_ACL_FLAG_ACCESS_FAIL
Definition daos_security.h:114

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