OpenVAS Libraries  6.0+beta5
Data Structures | Macros | Typedefs | Enumerations | Functions
openvas_auth.c File Reference

Authentication mechanisms used by openvas-manager and openvas-administrator. More...

#include "openvas_auth.h"
#include "openvas_uuid.h"
#include "openvas_file.h"
#include "array.h"
#include <errno.h>
#include <gcrypt.h>
#include <glib/gstdio.h>

Data Structures

struct  authenticator
 Representation of an abstract authentication mechanism. More...
 

Macros

#define AUTH_CONF_FILE   ".auth.conf"
 
#define GROUP_PREFIX_METHOD   "method:"
 
#define KEY_ORDER   "order"
 
#define RULES_FILE_HEADER   "# This file is managed by the OpenVAS Administrator.\n# Any modifications must keep to the format that the Administrator expects.\n"
 
#define G_LOG_DOMAIN   "lib auth"
 GLib logging domain. More...
 

Typedefs

typedef enum authentication_method auth_method_t
 Type for the numerical representation of the supported. More...
 
typedef struct authenticatorauthenticator_t
 Authenticator type. More...
 

Enumerations

enum  authentication_method {
  AUTHENTICATION_METHOD_FILE = 0, AUTHENTICATION_METHOD_ADS, AUTHENTICATION_METHOD_LDAP, AUTHENTICATION_METHOD_LDAP_CONNECT,
  AUTHENTICATION_METHOD_LAST
}
 Numerical representation of the supported authentication methods. More...
 

Functions

void openvas_auth_init ()
 Initializes the list of authentication methods. More...
 
void openvas_auth_tear_down ()
 Free memory associated to authentication configuration. More...
 
int openvas_auth_write_config (GKeyFile *key_file)
 Writes the authentication mechanism configuration, merging with. More...
 
gchar * digest_hex (int gcrypt_algorithm, const guchar *digest)
 Generate a hexadecimal representation of a message digest. More...
 
gchar * get_password_hashes (int digest_algorithm, const gchar *password)
 Generate a pair of hashes to be used in the OpenVAS "auth/hash" file for the user. More...
 
int openvas_authenticate (const gchar *username, const gchar *password)
 Authenticate a credential pair. More...
 
int openvas_authenticate_uuid (const gchar *username, const gchar *password, gchar **uuid)
 Authenticate a credential pair, returning the user UUID. More...
 
int openvas_user_exists (const char *name)
 Check whether a user exists. More...
 
gchar * openvas_user_uuid (const char *name)
 Return the UUID of a user from the OpenVAS user UUID file. More...
 
int openvas_is_user_admin (const gchar *username)
 Check if a user has administrative privileges. More...
 
int openvas_is_user_observer (const gchar *username)
 Check if a user is an observer. More...
 
int openvas_user_modify (const gchar *name, const gchar *password, const gchar *role, const gchar *hosts, int hosts_allow, const gchar *directory, const array_t *allowed_methods)
 Modify a user. More...
 
int openvas_auth_user_set_allowed_methods (const gchar *username, const array_t *allowed_methods)
 Place files in users /auth/methods/ directory indicating the. More...
 
int openvas_set_user_role (const gchar *username, const gchar *role, const gchar *user_dir_name)
 Set the role of a user. More...
 
int openvas_auth_user_uuid_rules (const gchar *username, const gchar *user_uuid, gchar **rules)
 Get host access rules for a certain user. More...
 
int openvas_auth_user_rules (const gchar *username, gchar **rules)
 Get host access rules for a certain user for file-based ("classic") More...
 
int openvas_auth_mkrulesdir (const gchar *user_dir_name)
 Creates the directory for the users rules (userdir/auth), if it does. More...
 
GSList * openvas_auth_user_methods (const gchar *user_name)
 Get list of methods allowed to use for a given user. More...
 
int openvas_auth_store_user_rules (const gchar *user_dir_name, const gchar *hosts, int hosts_allow)
 Stores the rules for a user. More...
 

Detailed Description

Authentication mechanisms used by openvas-manager and openvas-administrator.

Authentication Mechanisms

Three authentication mechanisms are supported:

These mechanisms are also used for authorization (role and access management).

Also a mixture can be used. To do so, a configuration file (PREFIX/var/lib/openvas/.auth.conf) has to be used and the authentication system has to be initialised with a call to openvas_auth_init and can be freed with openvas_auth_tear_down .

In addition, there is an authentication mechanism that can be enabled per user and does not do authorization (role and access management).

The configuration file allows to specify details of a remote ldap and/or ads authentication and to assign an "order" value to the specified authentication mechanisms. Mechanisms with a lower order will be tried first.

User Directories

Each user has a directory somewhere under OPENVAS_STATE_DIR. The directories of locally authenticated users reside under OPENVAS_STATE_DIR/users . The directory of remotely authenticated users reside under OPENVAS_STATE_DIR/users-remote/[method] , where [method] currently can only be "ldap" or "ads".

A users directory will contain:

Macro Definition Documentation

#define AUTH_CONF_FILE   ".auth.conf"
#define G_LOG_DOMAIN   "lib auth"

GLib logging domain.

#define GROUP_PREFIX_METHOD   "method:"
#define KEY_ORDER   "order"
#define RULES_FILE_HEADER   "# This file is managed by the OpenVAS Administrator.\n# Any modifications must keep to the format that the Administrator expects.\n"

Typedef Documentation

Type for the numerical representation of the supported.

authentication methods.

typedef struct authenticator* authenticator_t

Authenticator type.

Enumeration Type Documentation

Numerical representation of the supported authentication methods.

Beware to have it in sync with authentication_methods.

Enumerator
AUTHENTICATION_METHOD_FILE 
AUTHENTICATION_METHOD_ADS 
AUTHENTICATION_METHOD_LDAP 
AUTHENTICATION_METHOD_LDAP_CONNECT 
AUTHENTICATION_METHOD_LAST 

Function Documentation

gchar* digest_hex ( int  gcrypt_algorithm,
const guchar *  digest 
)

Generate a hexadecimal representation of a message digest.

Parameters
gcrypt_algorithmThe libgcrypt message digest algorithm used to create the digest (e.g. GCRY_MD_MD5; see the enum gcry_md_algos in gcrypt.h).
digestThe binary representation of the digest.
Returns
A pointer to the hexadecimal representation of the message digest or NULL if an unavailable message digest algorithm was selected.
gchar* get_password_hashes ( int  digest_algorithm,
const gchar *  password 
)

Generate a pair of hashes to be used in the OpenVAS "auth/hash" file for the user.

The "auth/hash" file consist of two hashes, h_1 and h_2. h_2 (the "seed") is the message digest of (currently) 256 bytes of random data. h_1 is the message digest of h_2 concatenated with the password in plaintext.

The current implementation was taken from the openvas-adduser shell script provided with openvas-server.

Parameters
gcrypt_algorithmThe libgcrypt message digest algorithm used to create the digest (e.g. GCRY_MD_MD5; see the enum gcry_md_algos in gcrypt.h)
passwordThe password in plaintext.
Returns
A pointer to a gchar containing the two hashes separated by a space or NULL if an unavailable message digest algorithm was selected.
void openvas_auth_init ( )

Initializes the list of authentication methods.

Parses PREFIX/var/lib/openvas/.auth.conf and adds respective authenticators to the authenticators list.

Call once before calls to openvas_authenticate, otherwise the authentication method will default to file-system based authentication.

The list should be freed with openvas_auth_tear_down once no further authentication trials will be done.

A warning will be issued if openvas_auth_init is called a second time without a call to openvas_auth_tear_down in between. In this case, no reconfiguration will take place.

int openvas_auth_mkrulesdir ( const gchar *  user_dir_name)

Creates the directory for the users rules (userdir/auth), if it does.

not yet exist.

Warning
Due to access () system calls nested in employed GLib functions,
this function might behave differently than expected in setuid
binaries.
Parameters
[in]user_dir_nameThe users directory.
Returns
0 if directory existed or was created, -1 if it could not be created.
int openvas_auth_store_user_rules ( const gchar *  user_dir_name,
const gchar *  hosts,
int  hosts_allow 
)

Stores the rules for a user.

The rules will be saved in a file in user_dir_name /auth/rules . This directory has to exist prior to this function call, otherwise the file will not be written and -1 will be returned.

Parameters
[in]user_dir_nameDirectory under which the auth/rules file will be placed.
[in]hostsThe hosts the user is allowed/forbidden to scan. Can be NULL, then defaults to allow-all.
[in]hosts_allowWhether access to hosts is allowed (!=0) or forbidden (0).
Returns
0 if successfull, -1 if an error occurred.
Todo:
Do better format checking on hosts.
void openvas_auth_tear_down ( )

Free memory associated to authentication configuration.

This will have no effect if openvas_auth_init was not called.

Todo:
Close memleak, destroy list and content.
GSList* openvas_auth_user_methods ( const gchar *  user_name)

Get list of methods allowed to use for a given user.

Note that currently only the ldap_connect method repsects this setting.

Parameters
[in]user_namename of the user.
Returns
List of strings with methods allowed for user.
int openvas_auth_user_rules ( const gchar *  username,
gchar **  rules 
)

Get host access rules for a certain user for file-based ("classic")

authentication.

Deprecated:
Use openvas_auth_user_uuid_rules where possible (need to know the uuid of user). Use openvas_authenticate_uuid to obtain a users uuid if not known.
Parameters
[in]usernameName of the user to get rules for.
[out]rulesReturn location for rules.
Returns
0 on failure, != 0 on success.
Todo:
access error message here, or pass it up.
int openvas_auth_user_set_allowed_methods ( const gchar *  username,
const array_t allowed_methods 
)

Place files in users /auth/methods/ directory indicating the.

allowed authentication methods for this user.

Note that currently only the ldap_connect method takes advantage of this mechanism.

Parameters
[in]usernameName of the user (to find the correct directory).
[in]allowed_methodslist of strings matching the allowed methods.
Returns
0 if operation failed. 1 otherwise.
int openvas_auth_user_uuid_rules ( const gchar *  username,
const gchar *  user_uuid,
gchar **  rules 
)

Get host access rules for a certain user.

Parameters
[in]usernameName of the user to get rules for.
[in]uuidUUID of user, needed to tell apart two or more users with the same name (e.g. locally and remotely authenticated). Can be NULL, then fall back to locally authenticated users only.
[out]rulesReturn location for rules.
Returns
0 on failure, != 0 on success.
Todo:
access error message here, or pass it up.
int openvas_auth_write_config ( GKeyFile *  key_file)

Writes the authentication mechanism configuration, merging with.

defaults and existing configuration.

If the passed key-file contains just one of the two groups (method:ldap and method:ads), do not write the defaults of the other group.

Parameters
[in]keyfileThe KeyFile to merge and write. Can be NULL, in which case just the default will be written.
Returns
0 if file has been written successfully, 1 authdn validation failed, -1 error.
Todo:
Preserve comments in file.
int openvas_authenticate ( const gchar *  username,
const gchar *  password 
)

Authenticate a credential pair.

Uses the configurable authenticators list, if available. Defaults to file-based (openvas users directory) authentication otherwise.

Parameters
usernameUsername, might not contain %-sign (otherwise -1 is returned).
passwordPassword.
Returns
0 authentication success, otherwise the result of the last authentication trial: 1 authentication failure, -1 error.
int openvas_authenticate_uuid ( const gchar *  username,
const gchar *  password,
gchar **  uuid 
)

Authenticate a credential pair, returning the user UUID.

Parameters
usernameUsername.
passwordPassword.
uuidUUID return.
Returns
0 authentication success, 1 authentication failure, -1 error.
int openvas_is_user_admin ( const gchar *  username)

Check if a user has administrative privileges.

The check for administrative privileges is currently done by looking for an "isadmin" file in the user directory.

Parameters
usernameUsername.
Warning
No "sharp" test is performed, as it is possible to have multiple users with the same name (in order to allow integration of remote authentication sources). Would need the uuid here to fix this behaviour.
Returns
1 user has administrative privileges, 0 user does not have administrative privileges
int openvas_is_user_observer ( const gchar *  username)

Check if a user is an observer.

The check for administrative privileges is currently done by looking for an "ispassword" file in the user directory.

Parameters
usernameUsername.
Warning
No "sharp" test is performed, as it is possible to have multiple users with the same name (in order to allow integration of remote authentication sources). Would need the uuid here to fix this behaviour.
Returns
1 if user is observer, else 0.
int openvas_set_user_role ( const gchar *  username,
const gchar *  role,
const gchar *  user_dir_name 
)

Set the role of a user.

Parameters
usernameUsername.
roleRole.
user_dir_nameDirectory of user. Can be NULL than the default (for locally authenticated users) will be taken.
Returns
0 success, -1 failure, -2 unknown role.
int openvas_user_exists ( const char *  name)

Check whether a user exists.

Parameters
[in]nameUser name.
Returns
1 yes, 0 no, -1 error.
int openvas_user_modify ( const gchar *  name,
const gchar *  password,
const gchar *  role,
const gchar *  hosts,
int  hosts_allow,
const gchar *  directory,
const array_t allowed_methods 
)

Modify a user.

Todo:
handle remotely authenticated users.
Parameters
[in]nameThe name of the new user.
[in]passwordThe password of the new user. NULL to leave as is.
[in]roleThe role of the user. NULL to leave as is.
[in]hostsThe host the user is allowed/forbidden to scan. NULL to leave as is.
[in]hosts_allowWhether hosts is allow or forbid.
[in]directoryThe directory containing the user directories. It will be created if it does not exist already.
[in]allowed_methodsArray of strings of allowed authenticators. If NULL, do no modifications.
Returns
0 if the user has been added successfully, -1 on error, -2 for an unknown role, -3 if user exists already.
gchar* openvas_user_uuid ( const char *  name)

Return the UUID of a user from the OpenVAS user UUID file.

If the user exists, ensure that the user has a UUID (create that file).

Parameters
[in]nameUser name.
Returns
UUID of given user if (locally authenticated) user exists, else NULL.