GCredentials: GIO Reference Manual

GCredentials

GCredentials — An object containing credentials

Functions

GCredentials *	g_credentials_new ()
gchar *	g_credentials_to_string ()
gpointer	g_credentials_get_native ()
void	g_credentials_set_native ()
gboolean	g_credentials_is_same_user ()
uid_t	g_credentials_get_unix_user ()
gboolean	g_credentials_set_unix_user ()
pid_t	g_credentials_get_unix_pid ()

Types and Values

	GCredentials
enum	GCredentialsType

Object Hierarchy

    GEnum
    ╰── GCredentialsType
    GObject
    ╰── GCredentials

Includes

#include <gio/gio.h>

Description

The GCredentials type is a reference-counted wrapper for native credentials. This information is typically used for identifying, authenticating and authorizing other processes.

Some operating systems supports looking up the credentials of the remote peer of a communication endpoint - see e.g. g_socket_get_credentials().

Some operating systems supports securely sending and receiving credentials over a Unix Domain Socket, see GUnixCredentialsMessage, g_unix_connection_send_credentials() and g_unix_connection_receive_credentials() for details.

On Linux, the native credential type is a struct ucred - see the unix(7) man page for details. This corresponds to G_CREDENTIALS_TYPE_LINUX_UCRED.

On Apple operating systems (including iOS, tvOS, and macOS), the native credential type is a struct xucred. This corresponds to G_CREDENTIALS_TYPE_APPLE_XUCRED.

On FreeBSD, Debian GNU/kFreeBSD, and GNU/Hurd, the native credential type is a struct cmsgcred. This corresponds to G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED.

On NetBSD, the native credential type is a struct unpcbid. This corresponds to G_CREDENTIALS_TYPE_NETBSD_UNPCBID.

On OpenBSD, the native credential type is a struct sockpeercred. This corresponds to G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED.

On Solaris (including OpenSolaris and its derivatives), the native credential type is a ucred_t. This corresponds to G_CREDENTIALS_TYPE_SOLARIS_UCRED.

Functions

g_credentials_new ()

GCredentials *
g_credentials_new (void);

Creates a new GCredentials object with credentials matching the the current process.

Returns

A GCredentials. Free with g_object_unref().

[transfer full]

Since: 2.26

g_credentials_to_string ()

gchar *
g_credentials_to_string (GCredentials *credentials);

Creates a human-readable textual representation of credentials that can be used in logging and debug messages. The format of the returned string may change in future GLib release.

Parameters

credentials

A GCredentials object.

Returns

A string that should be freed with g_free().

[transfer full]

Since: 2.26

g_credentials_get_native ()

gpointer
g_credentials_get_native (GCredentials *credentials,
                          GCredentialsType native_type);

Gets a pointer to native credentials of type native_type from credentials .

It is a programming error (which will cause a warning to be logged) to use this method if there is no GCredentials support for the OS or if native_type isn't supported by the OS.

[skip]

Parameters

credentials	A GCredentials.
native_type	The type of native credentials to get.

Returns

The pointer to native credentials or NULL if there is no GCredentials support for the OS or if native_type isn't supported by the OS. Do not free the returned data, it is owned by credentials .

[transfer none][nullable]

Since: 2.26

g_credentials_set_native ()

void
g_credentials_set_native (GCredentials *credentials,
                          GCredentialsType native_type,
                          gpointer native);

Copies the native credentials of type native_type from native into credentials .

It is a programming error (which will cause a warning to be logged) to use this method if there is no GCredentials support for the OS or if native_type isn't supported by the OS.

Parameters

credentials	A GCredentials.
native_type	The type of native credentials to set.
native	A pointer to native credentials.	[not nullable]

Since: 2.26

g_credentials_is_same_user ()

gboolean
g_credentials_is_same_user (GCredentials *credentials,
                            GCredentials *other_credentials,
                            GError **error);

Checks if credentials and other_credentials is the same user.

This operation can fail if GCredentials is not supported on the the OS.

Parameters

credentials	A GCredentials.
other_credentials	A GCredentials.
error	Return location for error or `NULL`.

Returns

TRUE if credentials and other_credentials has the same user, FALSE otherwise or if error is set.

Since: 2.26

g_credentials_get_unix_user ()

uid_t
g_credentials_get_unix_user (GCredentials *credentials,
                             GError **error);

Tries to get the UNIX user identifier from credentials . This method is only available on UNIX platforms.

This operation can fail if GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user.

Parameters

credentials	A GCredentials
error	Return location for error or `NULL`.

Returns

The UNIX user identifier or -1 if error is set.

Since: 2.26

g_credentials_set_unix_user ()

gboolean
g_credentials_set_unix_user (GCredentials *credentials,
                             uid_t uid,
                             GError **error);

Tries to set the UNIX user identifier on credentials . This method is only available on UNIX platforms.

This operation can fail if GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX user. It can also fail if the OS does not allow the use of "spoofed" credentials.

Parameters

credentials	A GCredentials.
uid	The UNIX user identifier to set.
error	Return location for error or `NULL`.

Returns

TRUE if uid was set, FALSE if error is set.

Since: 2.26

g_credentials_get_unix_pid ()

pid_t
g_credentials_get_unix_pid (GCredentials *credentials,
                            GError **error);

Tries to get the UNIX process identifier from credentials . This method is only available on UNIX platforms.

This operation can fail if GCredentials is not supported on the OS or if the native credentials type does not contain information about the UNIX process ID (for example this is the case for G_CREDENTIALS_TYPE_APPLE_XUCRED).

Parameters

credentials	A GCredentials
error	Return location for error or `NULL`.

Returns

The UNIX process ID, or -1 if error is set.

Since: 2.36

Types and Values

GCredentials

typedef struct _GCredentials GCredentials;

The GCredentials structure contains only private data and should only be accessed using the provided API.

Since: 2.26

enum GCredentialsType

Enumeration describing different kinds of native credential types.

Members

G_CREDENTIALS_TYPE_INVALID	Indicates an invalid native credential type.
G_CREDENTIALS_TYPE_LINUX_UCRED	The native credentials type is a `struct ucred`.
G_CREDENTIALS_TYPE_FREEBSD_CMSGCRED	The native credentials type is a `struct cmsgcred`.
G_CREDENTIALS_TYPE_OPENBSD_SOCKPEERCRED	The native credentials type is a `struct sockpeercred`. Added in 2.30.
G_CREDENTIALS_TYPE_SOLARIS_UCRED	The native credentials type is a `ucred_t`. Added in 2.40.
G_CREDENTIALS_TYPE_NETBSD_UNPCBID	The native credentials type is a `struct unpcbid`. Added in 2.42.
G_CREDENTIALS_TYPE_APPLE_XUCRED	The native credentials type is a `struct xucred`. Added in 2.66.

Since: 2.26