OpenVAS Libraries
6.0+beta5
|
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 authenticator * | authenticator_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... | |
Authentication mechanisms used by openvas-manager and openvas-administrator.
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.
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:
#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 enum authentication_method auth_method_t |
Type for the numerical representation of the supported.
authentication methods.
typedef struct authenticator* authenticator_t |
Authenticator type.
gchar* digest_hex | ( | int | gcrypt_algorithm, |
const guchar * | digest | ||
) |
Generate a hexadecimal representation of a message digest.
gcrypt_algorithm | The libgcrypt message digest algorithm used to create the digest (e.g. GCRY_MD_MD5; see the enum gcry_md_algos in gcrypt.h). |
digest | The binary representation of the digest. |
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.
gcrypt_algorithm | The libgcrypt message digest algorithm used to create the digest (e.g. GCRY_MD_MD5; see the enum gcry_md_algos in gcrypt.h) |
password | The password in plaintext. |
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.
[in] | user_dir_name | The users directory. |
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.
[in] | user_dir_name | Directory under which the auth/rules file will be placed. |
[in] | hosts | The hosts the user is allowed/forbidden to scan. Can be NULL, then defaults to allow-all. |
[in] | hosts_allow | Whether access to hosts is allowed (!=0) or forbidden (0). |
void openvas_auth_tear_down | ( | ) |
Free memory associated to authentication configuration.
This will have no effect if openvas_auth_init was not called.
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.
[in] | user_name | name of the user. |
int openvas_auth_user_rules | ( | const gchar * | username, |
gchar ** | rules | ||
) |
Get host access rules for a certain user for file-based ("classic")
authentication.
[in] | username | Name of the user to get rules for. |
[out] | rules | Return location for rules. |
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.
[in] | username | Name of the user (to find the correct directory). |
[in] | allowed_methods | list of strings matching the allowed methods. |
int openvas_auth_user_uuid_rules | ( | const gchar * | username, |
const gchar * | user_uuid, | ||
gchar ** | rules | ||
) |
Get host access rules for a certain user.
[in] | username | Name of the user to get rules for. |
[in] | uuid | UUID 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] | rules | Return location for rules. |
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.
[in] | keyfile | The KeyFile to merge and write. Can be NULL, in which case just the default will be written. |
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.
username | Username, might not contain %-sign (otherwise -1 is returned). |
password | Password. |
int openvas_authenticate_uuid | ( | const gchar * | username, |
const gchar * | password, | ||
gchar ** | uuid | ||
) |
Authenticate a credential pair, returning the user UUID.
username | Username. |
password | Password. |
uuid | UUID return. |
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.
username | Username. |
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.
username | Username. |
int openvas_set_user_role | ( | const gchar * | username, |
const gchar * | role, | ||
const gchar * | user_dir_name | ||
) |
Set the role of a user.
username | Username. |
role | Role. |
user_dir_name | Directory of user. Can be NULL than the default (for locally authenticated users) will be taken. |
int openvas_user_exists | ( | const char * | name) |
Check whether a user exists.
[in] | name | User name. |
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.
[in] | name | The name of the new user. |
[in] | password | The password of the new user. NULL to leave as is. |
[in] | role | The role of the user. NULL to leave as is. |
[in] | hosts | The host the user is allowed/forbidden to scan. NULL to leave as is. |
[in] | hosts_allow | Whether hosts is allow or forbid. |
[in] | directory | The directory containing the user directories. It will be created if it does not exist already. |
[in] | allowed_methods | Array of strings of allowed authenticators. If NULL, do no modifications. |
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).
[in] | name | User name. |