RSBAC_PM(2)

NAME
rsbac_pm - dispatcher for all RSBAC PM administration functions

SYNOPSIS
#include <rsbac/pm_types.h>

#include <rsbac/syscalls.h>

int rsbac_pm(enum rsbac_pm_function_type_t function, union rsbac_pm_function_param_t * param_p, rsbac_pm_tkt_id_t ticket);

DESCRIPTION
rsbac_pm is a dispatcher for all PM administration functions. It calls function function with respective parameters pointed to by param_p.

For many functions a ticket is needed (see PM model description). The ticket must be created by a user in another role (mostly data protection officer) first using the create_ticket function. The chosen ticket handle ticket is used to reference the actual ticket, which includes the function to be called, its parameters and a time-to-live.

The data structures are defined in pm_types.h and pm_ticket.h as follows:

    pm_types.h:
    #include <linux/types.h>
    /* Basic types */
    typedef u_int rsbac_pm_task_id_t;
    typedef u_int rsbac_pm_tp_id_t; /* transformation procedure id */
    typedef u_int rsbac_pm_purpose_id_t;
    typedef u_int rsbac_pm_object_class_id_t;
    typedef u_int rsbac_pm_tkt_id_t;      /* ticket id */
    typedef long rsbac_pm_time_stamp_t;   /* for ticket time stamps, same as */
                                          /* parameter for sys_time */
    typedef u_char rsbac_pm_accesses_t;   /* for necessary accesses */
    #define RSBAC_PM_A_READ   1
    #define RSBAC_PM_A_WRITE  2
    #define RSBAC_PM_A_DELETE 4
    #define RSBAC_PM_A_CREATE 8
    #define RSBAC_PM_A_APPEND 16
    #define RSBAC_PM_A_ALL    31
    #define RSBAC_PM_A_WRITING (RSBAC_PM_A_WRITE | RSBAC_PM_A_DELETE                             | RSBAC_PM_A_CREATE | RSBAC_PM_A_APPEND)
    #define RSBAC_PM_A_WRITE_TO_FILE (RSBAC_PM_A_WRITE | RSBAC_PM_A_APPEND)
    #define RSBAC_PM_IPC_OBJECT_CLASS_ID  (rsbac_pm_object_class_id_t) 60000
    #define RSBAC_PM_DEV_OBJECT_CLASS_ID  (rsbac_pm_object_class_id_t) 60001
    /* enum attributes */
    enum    rsbac_pm_all_list_t {PA_task,PA_class,PA_na,PA_cs,PA_tp,
                                 PA_pp,PA_tkt,PA_task_set,PA_tp_set,
                                 PA_ru_set,PA_pp_set,PA_in_pp_set,
                                 PA_out_pp_set,PA_none};
    enum    rsbac_pm_role_t {PR_user,PR_security_officer,
                             PR_data_protection_officer,
                             PR_tp_manager,PR_system_admin,
                             PR_none};
    enum    rsbac_pm_process_type_t {PP_none, PP_TP};
    enum    rsbac_pm_object_type_t {PO_none, PO_TP, PO_personal_data,
                                    PO_non_personal_data, PO_ipc,
                                    PO_dir};
    typedef enum rsbac_pm_process_type_t rsbac_pm_program_type_t;
    struct rsbac_pm_purpose_list_item_t
        {
          rsbac_pm_purpose_id_t                 id;
          struct rsbac_pm_purpose_list_item_t * next;
        };

    pm_ticket.h:
    #include <linux/types.h>
    enum    rsbac_pm_tkt_function_type_t {
              /* issued by data_prot_officer */
              PTF_add_na, PTF_delete_na, PTF_add_task,
              PTF_delete_task, PTF_add_object_class,
              PTF_delete_object_class,
              PTF_add_authorized_tp,
              PTF_delete_authorized_tp,
              PTF_add_consent, PTF_delete_consent,
              PTF_add_purpose, PTF_delete_purpose,
              PTF_add_responsible_user,
              PTF_delete_responsible_user,
              PTF_delete_user_aci,
              PTF_set_role,
              PTF_set_object_class,
              PTF_switch_pm,
              PTF_set_device_object_type,
              /* issued by user also */
              PTF_add_authorized_task,
              PTF_delete_authorized_task,
              /* never issued, internal */
              PTF_none};
    struct rsbac_pm_add_na_t
      {
        rsbac_pm_task_id_t            task;
        rsbac_pm_object_class_id_t    class;
        rsbac_pm_tp_id_t              tp;
        rsbac_pm_accesses_t           accesses;
      };
    struct rsbac_pm_delete_na_t
      {
        rsbac_pm_task_id_t            task;
        rsbac_pm_object_class_id_t    class;
        rsbac_pm_tp_id_t              tp;
        rsbac_pm_accesses_t           accesses;
      };
    struct rsbac_pm_add_task_t
      {
        rsbac_pm_task_id_t            id;
        rsbac_pm_purpose_id_t         purpose;
      };
    struct rsbac_pm_delete_task_t
      {
        rsbac_pm_task_id_t            id;
      };
    struct rsbac_pm_add_object_class_t
      {
        rsbac_pm_object_class_id_t            id;
        struct rsbac_pm_purpose_list_item_t * pp_list_p;
      };
    struct rsbac_pm_delete_object_class_t
      {
        rsbac_pm_object_class_id_t    id;
      };
    struct rsbac_pm_add_authorized_tp_t
      {
        rsbac_pm_task_id_t            task;
        rsbac_pm_tp_id_t              tp;
      };
    struct rsbac_pm_delete_authorized_tp_t
      {
        rsbac_pm_task_id_t            task;
        rsbac_pm_tp_id_t              tp;
      };
    struct rsbac_pm_add_consent_t
      {
        char                        * filename;
               rsbac_pm_purpose_id_t  purpose;
      };
    struct rsbac_pm_delete_consent_t
      {
        char                        * filename;
        rsbac_pm_purpose_id_t         purpose;
      };
    struct rsbac_pm_add_purpose_t
      {
        rsbac_pm_purpose_id_t         id;
        rsbac_pm_object_class_id_t    def_class;
      };
    struct rsbac_pm_delete_purpose_t
      {
        rsbac_pm_purpose_id_t         id;
      };
    struct rsbac_pm_add_responsible_user_t
      {
        rsbac_uid_t                   user;
        rsbac_pm_task_id_t            task;
      };
    struct rsbac_pm_delete_responsible_user_t
      {
        rsbac_uid_t                   user;
        rsbac_pm_task_id_t            task;
      };
    struct rsbac_pm_delete_user_aci_t
      {
        rsbac_uid_t                   id;
      };
    struct rsbac_pm_set_role_t
      {
        rsbac_uid_t                   user;
        enum rsbac_pm_role_t          role;
      };
    struct rsbac_pm_set_object_class_t
      {
        char                        * filename;
        rsbac_pm_object_class_id_t    class;
      };
    struct rsbac_pm_switch_pm_t
      {
        boolean                       value;
      };
    struct rsbac_pm_set_device_object_type_t
      {
        char                        * filename;
        enum rsbac_pm_object_type_t   object_type;
        rsbac_pm_object_class_id_t    class;
      };
    /***************/
    struct rsbac_pm_add_authorized_task_t
      {
        rsbac_uid_t                   user;
        rsbac_pm_task_id_t            task;
      };
    struct rsbac_pm_delete_authorized_task_t
      {
        rsbac_uid_t                   user;
        rsbac_pm_task_id_t            task;
      };
    /***************/
    struct rsbac_pm_write_list_t
      {
        char                        * filename;
        enum rsbac_pm_all_list_t      list;
      };
    /*****************/
    struct rsbac_pm_create_tp_t
      {
        rsbac_pm_tp_id_t              id;
      };
    struct rsbac_pm_delete_tp_t
      {
        rsbac_pm_tp_id_t              id;
      };
    struct rsbac_pm_set_tp_t
      {
        char                        * filename;
        rsbac_pm_tp_id_t              tp;
      };
    /***************/
    union   rsbac_pm_tkt_function_param_t
     {
       struct rsbac_pm_add_na_t                   add_na;
       struct rsbac_pm_delete_na_t                delete_na;
       struct rsbac_pm_add_task_t                 add_task;
       struct rsbac_pm_delete_task_t              delete_task;
       struct rsbac_pm_add_object_class_t         add_object_class;
       struct rsbac_pm_delete_object_class_t      delete_object_class;
       struct rsbac_pm_add_authorized_tp_t        add_authorized_tp;
       struct rsbac_pm_delete_authorized_tp_t     delete_authorized_tp;
       struct rsbac_pm_add_consent_t              add_consent;
       struct rsbac_pm_delete_consent_t           delete_consent;
       struct rsbac_pm_add_purpose_t              add_purpose;
       struct rsbac_pm_delete_purpose_t           delete_purpose;
       struct rsbac_pm_add_responsible_user_t     add_responsible_user;
       struct rsbac_pm_delete_responsible_user_t  delete_responsible_user;
       struct rsbac_pm_delete_user_aci_t          delete_user_aci;
       struct rsbac_pm_set_role_t                 set_role;
       struct rsbac_pm_set_object_class_t         set_object_class;
       struct rsbac_pm_switch_pm_t                switch_pm;
       struct rsbac_pm_set_device_object_type_t   set_device_object_type;
       struct rsbac_pm_add_authorized_task_t      add_authorized_task;
       struct rsbac_pm_delete_authorized_task_t   delete_authorized_task;
       int                                        dummy;
     };
    /***********************/
    enum    rsbac_pm_function_type_t {
              /* tkt issued by data_prot_officer, */
              /* called by security_officer */
              PF_add_na, PF_delete_na, PF_add_task,
              PF_delete_task, PF_add_object_class,
              PF_delete_object_class,
              PF_add_authorized_tp,
              PF_delete_authorized_tp,
              PF_add_consent, PF_delete_consent,
              PF_add_purpose, PF_delete_purpose,
              PF_add_responsible_user,
              PF_delete_responsible_user,
              PF_delete_user_aci,
              PF_set_role,
              PF_set_object_class,
              PF_switch_pm,
              PF_set_device_object_type,
              /* tkt issued by data_prot_officer and */
              /* resp. user, called by security_officer */
              PF_add_authorized_task,
              PF_delete_authorized_task,
              /* called by sec_off or data_prot, no ticket */
              PF_write_list,
              /* called by tp_manager, no ticket */
              PF_create_tp, PF_delete_tp, PF_set_tp,
              /* called by data_prot_officer and */
              /* responsible user */
              PF_create_ticket,
              /* never to be called, internal */
              PF_none};
    struct rsbac_pm_create_ticket_t
      {
               rsbac_pm_tkt_id_t              id;
               rsbac_pm_time_stamp_t          valid_for;  /* validity in secs */
        enum   rsbac_pm_tkt_function_type_t   function_type;
        union  rsbac_pm_tkt_function_param_t  function_param;
      };
    union   rsbac_pm_function_param_t
      {
        struct rsbac_pm_add_na_t                   add_na;
        struct rsbac_pm_delete_na_t                delete_na;
        struct rsbac_pm_add_task_t                 add_task;
        struct rsbac_pm_delete_task_t              delete_task;
        struct rsbac_pm_add_object_class_t         add_object_class;
        struct rsbac_pm_delete_object_class_t      delete_object_class;
        struct rsbac_pm_add_authorized_tp_t        add_authorized_tp;
        struct rsbac_pm_delete_authorized_tp_t     delete_authorized_tp;
        struct rsbac_pm_add_consent_t              add_consent;
        struct rsbac_pm_delete_consent_t           delete_consent;
        struct rsbac_pm_add_purpose_t              add_purpose;
        struct rsbac_pm_delete_purpose_t           delete_purpose;
        struct rsbac_pm_add_responsible_user_t     add_responsible_user;
        struct rsbac_pm_delete_responsible_user_t  delete_responsible_user;
        struct rsbac_pm_delete_user_aci_t          delete_user_aci;
        struct rsbac_pm_set_role_t                 set_role;
        struct rsbac_pm_set_object_class_t         set_object_class;
        struct rsbac_pm_switch_pm_t                switch_pm;
        struct rsbac_pm_set_device_object_type_t   set_device_object_type;
        struct rsbac_pm_add_authorized_task_t      add_authorized_task;
        struct rsbac_pm_delete_authorized_task_t   delete_authorized_task;
        struct rsbac_pm_write_list_t               write_list;
        struct rsbac_pm_create_tp_t                create_tp;
        struct rsbac_pm_delete_tp_t                delete_tp;
        struct rsbac_pm_set_tp_t                   set_tp;
        struct rsbac_pm_create_ticket_t            create_ticket;
        int                                        dummy;
      };

RETURN VALUE
rsbac_pm returns 0 on success and an error code otherwise.

ERRORS

EPERM
    The user/process is not allowed to call this function in this way, e.g. wrong pm_role, ticket not existing or outdated.

RSBAC_EINVALIDREQUEST
    The function is invalid.

RSBAC_EINVALIDPOINTER
    param_p is NULL.

RSBAC_EINVALIDVALUE
    A parameter value is invalid, e.g. a referenced object does not exist.

RSBAC_EINVALIDTARGET
    The function target is invalid, e.g. should be a file, but is a dir.

RSBAC_ENOTINITIALIZED
    The RSBAC system is not initialized, so no attributes are available.

RSBAC_EREADFAILED
    The RSBAC system ran into an error while getting an attribute.

RSBAC_EWRITEFAILED
    The RSBAC system ran into an error while setting the attribute.

RSBAC_EEXIST
    The ticket or object id exists, choose another one.

SEE ALSO
rsbac_pm_change_current_task(2),rsbac_pm_create_file(2).

AUTHOR
Amon Ott <ao@compuniverse.com>