access.h

 
/* SPDX-FileCopyrightText: Copyright 2020 Rick van Rein <rick@openfortress.nl>
 * SPDX-License-Identifier: BSD-2-Clause
 */
 
 
#ifndef ARPA2_ACCESS_H
#define ARPA2_ACCESS_H
 
 
#include <stdbool.h>
#include <stdint.h>
 
#include "arpa2/identity.h"
#include "arpa2/rules.h"
 
 
#ifdef __cplusplus
extern "C" {
#endif
 
 
typedef rules_domain access_domain;
 
 
typedef rules_type access_type;
 
 
typedef rules_name access_name;
 
 
typedef rules_flags access_rights;
 
 
#define ACCESS_RIGHT(c) ( 1 << (c - 'A') )
 
 
/* Rights to resources, from the highest grade to lower,
 * though it is up to the resource settings to actually
 * allow lower-grade rights along with higher-grade
 * rights like set with the _DOWN definitions below -- or
 * they may choose to withhold those implied privileges.
 * Applications have the opposite option; they may reason
 * that higher rights grant lower privileges, and use the
 * _UP macros to derive the bit mask to work with.  There
 * is no harm in combining these approaches.
 *
 * ACCESS_ADMIN is the highest privilege, reserved for humans
 *      with overall access to everything.
 *
 * ACCESS_SERVICE is the highest automation privilege, reserved
 *      for bots and such performing administrative changes.
 *
 * ACCESS_CONFIGURE is the right to modify the configuration of
 *      a service.
 *
 * ACCESS_OPERATE is the right to start or stop a service, not
 *      knowing anything about its contents or resources.
 *
 * ACCESS_DELETE is the right to delete a resource.  This is
 *      the highest resource right because it can undo all
 *      the other levels.
 *
 * ACCESS_CREATE is the right to create a resource.  Other than
 *      perhaps defining a name or retrieving an identity is
 *      not permitted with this, and certainly no changes.
 *
 * ACCESS_EXECUTE is the right to run a service or make a
 *      resource do something, such as accepting connections.
 *
 * ACCESS_WRITE is the right to write to an existing resource.
 *
 * ACCESS_READ is the right to read from an existing resource.
 *
 * ACCESS_PROVE is the right to prove properties about the
 *      resource.  An example could be a password check
 *      without actually seeing a key stored for that use.
 *
 * ACCESS_KNOW is the right to know about the existence of a
 *      resource.  It is not the right to know anything about
 *      its contents, nor to create or delete resources.
 *
 * ACCESS_OWNER is the right to own a resource.  This may sound
 *      like a lot, but it really does not allow to do anything
 *      with it.  A directory or an account might have this
 *      right, for instance.  It is mostly useful to pin the
 *      owner on the resource.
 *
 * ACCESS_VISITOR is the lowest of all rights.  It allows no actual
 *      operations, not even to know whether a resource exists.
 *      It is the ultimate send-away ("kluitje in het riet") right.
 *
 * ACCESS_FORBIDDEN is not even a proper level.  It simply has no
 *      flags at all, and is a downright negative, "damn all"
 *      response.  Try to be careful about this one; normally
 *      you might be able to include a cautious ACCESS_VISITOR
 *      level.
 */
#define ACCESS_ADMIN   ACCESS_RIGHT('A')
#define ACCESS_SERVICE ACCESS_RIGHT('S')
#define ACCESS_CONFIG  ACCESS_RIGHT('F')
#define ACCESS_OPERATE ACCESS_RIGHT('T')
#define ACCESS_DELETE  ACCESS_RIGHT('D')
#define ACCESS_CREATE  ACCESS_RIGHT('C')
#define ACCESS_EXECUTE ACCESS_RIGHT('X')
#define ACCESS_WRITE   ACCESS_RIGHT('W')
#define ACCESS_READ    ACCESS_RIGHT('R')
#define ACCESS_PROVE   ACCESS_RIGHT('P')
#define ACCESS_KNOW    ACCESS_RIGHT('K')
#define ACCESS_OWNER   ACCESS_RIGHT('O')
#define ACCESS_VISITOR ACCESS_RIGHT('V')
//
#define ACCESS_FORBIDDEN 0
 
 
/* The ACL rights with their higher rights added, to allow for
 * easier tests of inclusiveness.
 */
#define ACCESS_ADMIN_UP   ( ACCESS_ADMIN   | 0               )
#define ACCESS_SERVICE_UP ( ACCESS_SERVICE | ACCESS_ADMIN_UP   )
#define ACCESS_CONFIG_UP  ( ACCESS_CONFIG  | ACCESS_SERVICE_UP )
#define ACCESS_OPERATE_UP ( ACCESS_OPERATE | ACCESS_CONFIG_UP  )
#define ACCESS_DELETE_UP  ( ACCESS_DELETE  | ACCESS_OPERATE_UP )
#define ACCESS_CREATE_UP  ( ACCESS_CREATE  | ACCESS_DELETE_UP  )
#define ACCESS_EXECUTE_UP ( ACCESS_EXECUTE | ACCESS_CREATE_UP  )
#define ACCESS_WRITE_UP   ( ACCESS_WRITE   | ACCESS_EXECUTE_UP )
#define ACCESS_READ_UP    ( ACCESS_READ    | ACCESS_WRITE_UP   )
#define ACCESS_PROVE_UP   ( ACCESS_PROVE   | ACCESS_READ_UP    )
#define ACCESS_KNOW_UP    ( ACCESS_KNOW    | ACCESS_PROVE_UP   )
#define ACCESS_OWNER_UP   ( ACCESS_OWNER   | ACCESS_KNOW_UP    )
#define ACCESS_VISITOR_UP ( ACCESS_VISITOR | ACCESS_OWNER_UP   )
 
 
/* The ACL rights with their lower rights added, to allow for
 * easier tests of inclusiveness.
 */
#define ACCESS_ADMIN_DOWN   ( ACCESS_ADMIN   | ACCESS_SERVICE_DOWN )
#define ACCESS_SERVICE_DOWN ( ACCESS_SERVICE | ACCESS_CONFIG_DOWN  )
#define ACCESS_CONFIG_DOWN  ( ACCESS_CONFIG  | ACCESS_OPERATE_DOWN )
#define ACCESS_OPERATE_DOWN ( ACCESS_OPERATE | ACCESS_DELETE_DOWN  )
#define ACCESS_DELETE_DOWN  ( ACCESS_DELETE  | ACCESS_CREATE_DOWN  )
#define ACCESS_CREATE_DOWN  ( ACCESS_CREATE  | ACCESS_EXECUTE_DOWN )
#define ACCESS_EXECUTE_DOWN ( ACCESS_EXECUTE | ACCESS_WRITE_DOWN   )
#define ACCESS_WRITE_DOWN   ( ACCESS_WRITE   | ACCESS_READ_DOWN    )
#define ACCESS_READ_DOWN    ( ACCESS_READ    | ACCESS_PROVE_DOWN   )
#define ACCESS_PROVE_DOWN   ( ACCESS_PROVE   | ACCESS_KNOW_DOWN    )
#define ACCESS_KNOW_DOWN    ( ACCESS_KNOW    | ACCESS_OWNER_DOWN   )
#define ACCESS_OWNER_DOWN   ( ACCESS_OWNER   | ACCESS_VISITOR_DOWN )
#define ACCESS_VISITOR_DOWN ( ACCESS_VISITOR | 0                 )
 
 
bool access_parse (char *userstr, access_rights *accumulator);
 
 
 
void access_format (const char *opt_fmtstr, access_rights rights, char *outstr);
 
 
static inline void access_init (void) {
        rules_init ();
}
 
 
static inline void access_fini (void) {
        rules_fini ();
}
 
 
const char *access_host2domain (const char *fqdn_hostname);
 
 
#ifdef __cplusplus
}
#endif
 
#endif /* ARPA2_ACCESS_H */