Indigresso Wiki

Open Source Stuff for DASH7

User Tools

Site Tools


opentag:otlib:auth

Authentication (OTlib)

The Authentication (Auth) Module is an integral part of OpenTag because it is an integral part of the DASH7 Filesystem. All files in the DASH7 Filesystem contain a byte used for permissions, and whenever a file is accessed its permissions must be measured against the authentication level of the user requesting this file's data. The Authentication Module does this job.

Authenticated Users

Depending on the amount of security support on the OpenTag device, the authentication module may perform key challenges, lookups, etc, or it may be as simple as a device that considers all remote users as guests.

Guest

A guest has guest-level access to files, which is typically the most restricted. The guest-level access is specified in the file permissions byte. In systems without crypto-secure authentication, the id_tmpl argument of file access functions should use the value AUTH_GUEST.

User/Admin

The user/admin has user-level access to files, which is typically unrestrictive. User-level access is not generally available unless there is some crypto-security layer available to the device. Without a key-exchange method, there is no good way to authenticate a Remote User (see below).

Root User

The Root User has implicit access to all files. Via the auth module, passing NULL (in C) as the user value will cause the file to be accessed by the root user. Internal calls may use AUTH_ROOT as the id_tmpl argument in file access functions. AUTH_ROOT maps to NULL, but do use AUTH_ROOT instead of NULL. Root users are always internal or via MPipe. Remote Users can never have Root permissions.

Remote User

A Remote User is any function caller that has originated from a DASH7 request command (or, really, anything other than an internal function call or an MPipe command function call). In devices without a crypto-security layer, remote users are always authenticated as guests.

OTlib/auth.h

The code from auth.h is pasted below, although you can also check the doxygen code documentation. As the Authentication Module is not fully written at the time of authoring (03-2012), you may want to check back to see if the interface has changed. Most likely, an NLS key function will be introduced and possibly the auth table will be modified slightly.

#include "OT_types.h"
#include "OTAPI.h"

/// Default user types
#define AUTH_GUEST  (id_tmpl*)auth_guest
#define AUTH_ROOT   NULL

#define AUTH_FLAG_ISGLOBAL  0x80
#define AUTH_FLAG_ISROOT    0x40

///@todo bring this into OT_config.h eventually, when the feature gets supported
#define AUTH_NUM_ELEMENTS 0

extern const id_tmpl*   auth_guest;


/** @typedef auth_entry
  * The auth_entry type stores information about the key.
  *
  * mod         (ot_u8)     ISGLOBAL, ISROOT then 6 bits of file permissions
  * user_mod    (ot_u8)     User's available mod (permissions)
  * lifetime    (ot_u32)    UTC time of when key expires
  * id          (id_tmpl*)  Device ID of user
  * key         (ot_u8*)    Key of user (length implied from protocol id)
  */
typedef struct {
    ot_u8       mod;
    ot_u8       protocol;
    ot_u32      lifetime;
    id_tmpl*    id;
    ot_u8*      key;
} auth_entry;


/** @brief Authentication Module Initializer
  * @param None
  * @retval None
  * @ingroup Authentication
  */
void auth_init();


/** @brief Returns True if the supplied user has root access
  * @param user_id      (id_tmpl*) pointer to a UID/VID template
  * @retval ot_bool     True when user is root
  * @ingroup Authentication
  */
ot_bool auth_isroot(id_tmpl* user_id);


/** @brief Checks the authentication data per supplied user, and provides yes or no
  * @param data_mod     (ot_u8) Veelite Mod value of the desired data element
  * @param req_mod      (ot_u8) Requested Mod for operation (e.g. read or write)
  * @param user_id      (id_tmpl*) pointer to a UID/VID template
  * @retval ot_u8       Non-zero when authentication is OK
  * @ingroup Authentication
  */
ot_u8 auth_check(ot_u8 data_mod, ot_u8 req_mod, id_tmpl* user_id);


/** @brief Adds a new key entry and associated key data to the Crypto_Heap.
  * @param new_entry : (crypto_entry*) pointer to crypto_entry to be added
  * @param new_data : (ot_u8*) key data for this entry
  * @retval auth_entry* : pointer to Key in Heap.  NULL on error.
  * @ingroup Authentication
  *
  * If a new key is added, but there is no room left, the oldest key will be
  * deleted to make room for this new key.
  */
auth_entry* auth_new_nlsuser(auth_entry* new_user, ot_u8* new_data);


/** @brief Searches and returns a key based on UID or VID (if UID is NULL).
  * @param user_id      (id_tmpl*) Device ID of user
  * @param mod_flags   (ot_u8) extra user flags to require
  * @retval auth_entry* : pointer to Key in Heap.  NULL on error. 
  * @ingroup Authentication
  */
auth_entry* auth_search_user(id_tmpl* user_id, ot_u8 mod_flags);


/** @brief Returns the stored User or Root key that matches the protocol ID
  * @param protocol (ot_u8) Protocol ID of the DLLS method
  * @param header   (ot_u8*) optional header data (defined by protocol ID) 
  * @retval ot_u8*  Key Data
  * @ingroup Authentication
  */
ot_u8* auth_get_dllskey(ot_u8 protocol, ot_u8* header);
opentag/otlib/auth.txt · Last modified: 2012/03/26 00:37 by jpnorair