OpenVAS Libraries  4.0+rc3.SVN
Data Structures | Defines | Typedefs | Enumerations | Functions
misc/openvas_auth.c File Reference

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

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

Data Structures

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

Defines

#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.

Typedefs

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

Enumerations

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

Functions

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

Detailed Description

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

Authentication Mechanisms

Three authentication mechanisms are supported:

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 .

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:


Typedef Documentation

Type for the numerical representation of the supported.

authentication methods.


Enumeration Type Documentation

Numerical representation of the supported authentication methods.

Beware to have it in sync with authentication_methods.


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  gcrypt_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 wich the autch/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.
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_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:
1 if file has been written successfully, != 1 otherwise.
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_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.
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).

Deprecated:
Use openvas_authenticate_uuid to receive users uuid where you can. This leaves an issue in manager/schedular, that is solveable by storing a uuid instead of manage_auth_allow_all in openvasmd.
Parameters:
[in]nameUser name.
Returns:
UUID of given user if (locally authenticated) user exists, else NULL.