GsAuth: GNOME Software Reference Manual

## GsAuth GsAuth — User data used for authentication |

## Stability Level

Unstable, unless otherwise indicated

## Functions

GsAuth * | gs_auth_new ()
const gchar * | gs_auth_get_provider_id ()
const gchar * | gs_auth_get_provider_name ()
void | gs_auth_set_provider_name ()
const gchar * | gs_auth_get_provider_logo ()
void | gs_auth_set_provider_logo ()
const gchar * | gs_auth_get_provider_uri ()
void | gs_auth_set_provider_uri ()
const gchar * | gs_auth_get_provider_schema ()
void | gs_auth_set_provider_schema ()
const gchar * | gs_auth_get_username ()
void | gs_auth_set_username ()
const gchar * | gs_auth_get_password ()
void | gs_auth_set_password ()
const gchar * | gs_auth_get_pin ()
void | gs_auth_set_pin ()
GsAuthFlags | gs_auth_get_flags ()
void | gs_auth_set_flags ()
void | gs_auth_add_flags ()
gboolean | gs_auth_has_flag ()
const gchar * | gs_auth_get_metadata_item ()
void | gs_auth_add_metadata ()
gboolean | gs_auth_store_load ()
gboolean | gs_auth_store_save ()
gboolean | gs_auth_store_clear ()

## Types and Values

#define | GS_TYPE_AUTH
enum | GsAuthFlags
enum | GsAuthStoreFlags
| GsAuth

## Includes

    #include <gnome-software.h>

## Description

This object represents user data used for authentication. This data is shared between all plugins.

## Functions

### gs_auth_new ()

    GsAuth *
    gs_auth_new (const gchar *provider_id);

#### Parameters

provider_id | a provider ID used for mapping, e.g. "GnomeSSO" |

#### Returns

a new GsAuth object.

### gs_auth_get_provider_id ()

    const gchar *
    gs_auth_get_provider_id (GsAuth *auth);

Gets the authentication service ID.

#### Parameters

auth | a GsAuth |

#### Returns

the string to use for searching, e.g. "UbuntuOne"

### gs_auth_get_provider_name ()

    const gchar *
    gs_auth_get_provider_name (GsAuth *auth);

Gets the authentication service name.

#### Parameters

auth | a GsAuth |

#### Returns

the string to show in the UI

### gs_auth_set_provider_name ()

    void
    gs_auth_set_provider_name (GsAuth *auth,
                               const gchar *provider_name);

Sets the name to be used for the authentication dialog.

#### Parameters

auth | a GsAuth |
provider_name | a service name, e.g. "GNOME Online Accounts" |

### gs_auth_get_provider_logo ()

    const gchar *
    gs_auth_get_provider_logo (GsAuth *auth);

Gets the authentication service image.

#### Parameters

auth | a GsAuth |

#### Returns

the filename of an image, or `NULL`

### gs_auth_set_provider_logo ()

    void
    gs_auth_set_provider_logo (GsAuth *auth,
                               const gchar *provider_logo);

Sets the image to be used for the authentication dialog.

#### Parameters

auth | a GsAuth |
provider_logo | an image, e.g. "/usr/share/icons/gnome-online.png" |

### gs_auth_get_provider_uri ()

    const gchar *
    gs_auth_get_provider_uri (GsAuth *auth);

Gets the authentication service website.

#### Parameters

auth | a GsAuth |

#### Returns

the URI, or `NULL`

### gs_auth_set_provider_uri ()

    void
    gs_auth_set_provider_uri (GsAuth *auth,
                              const gchar *provider_uri);

Sets the website to be used for the authentication dialog.

#### Parameters

auth | a GsAuth |
provider_uri | a URI, e.g. "http://www.gnome.org/sso" |

### gs_auth_get_provider_schema ()

    const gchar *
    gs_auth_get_provider_schema (GsAuth *auth);

Gets the authentication schema ID.

#### Parameters

auth | a GsAuth |

#### Returns

the URI, or `NULL`

### gs_auth_set_provider_schema ()

    void
    gs_auth_set_provider_schema (GsAuth *auth,
                                 const gchar *provider_schema);

Sets the schema ID to be used for saving the state to disk.

#### Parameters

auth | a GsAuth |
provider_schema | a URI, e.g. "com.distro.provider" |

### gs_auth_get_username ()

    const gchar *
    gs_auth_get_username (GsAuth *auth);

Gets the auth username.

#### Parameters

auth | a GsAuth |

#### Returns

the username to be used for the authentication

### gs_auth_set_username ()

    void
    gs_auth_set_username (GsAuth *auth,
                          const gchar *username);

Sets the username to be used for the authentication.

#### Parameters

auth | a GsAuth |
username | a username, e.g. "hughsie" |

### gs_auth_get_password ()

    const gchar *
    gs_auth_get_password (GsAuth *auth);

Gets the password to be used for the authentication.

#### Parameters

auth | a GsAuth |

#### Returns

the string, or `NULL`

### gs_auth_set_password ()

    void
    gs_auth_set_password (GsAuth *auth,
                          const gchar *password);

Sets the password to be used for the authentication.

#### Parameters

auth | a GsAuth |
password | password string, e.g. "p`ssw0rd` " |

### gs_auth_get_pin ()

    const gchar *
    gs_auth_get_pin (GsAuth *auth);

Gets the PIN code.

#### Parameters

auth | a GsAuth |

#### Returns

the 2 factor authentication PIN, or `NULL`

### gs_auth_set_pin ()

    void
    gs_auth_set_pin (GsAuth *auth,
                     const gchar *pin);

Sets the 2 factor authentication PIN, which can be left unset.

#### Parameters

auth | a GsAuth |
pin | the PIN code, e.g. "12345" |

### gs_auth_get_flags ()

    GsAuthFlags
    gs_auth_get_flags (GsAuth *auth);

Gets any flags set on the authentication, for example if we should remember credentials.

#### Parameters

auth | a GsAuth |

#### Returns

a GsAuthFlags, e.g. `GS_AUTH_FLAG_REMEMBER`

### gs_auth_set_flags ()

    void
    gs_auth_set_flags (GsAuth *auth,
                       GsAuthFlags flags);

Gets any flags set on the authentication.

#### Parameters

auth | a GsAuth |
flags | a GsAuthFlags, e.g. `GS_AUTH_FLAG_REMEMBER` |

### gs_auth_add_flags ()

    void
    gs_auth_add_flags (GsAuth *auth,
                       GsAuthFlags flags);

Adds flags to an existing authentication without replacing the other flags.

#### Parameters

auth | a GsAuth |
flags | a GsAuthFlags, e.g. `GS_AUTH_FLAG_REMEMBER` |

### gs_auth_has_flag ()

    gboolean
    gs_auth_has_flag (GsAuth *auth,
                      GsAuthFlags flags);

Finds out if the authentication has a flag.

#### Parameters

auth | a GsAuth |
flags | a GsAuthFlags, e.g. `GS_AUTH_FLAG_REMEMBER` |

#### Returns

`TRUE` if set

### gs_auth_get_metadata_item ()

    const gchar *
    gs_auth_get_metadata_item (GsAuth *auth,
                               const gchar *key);

Gets some metadata from a authentication object. It is left for the the plugin to use this method as required, but a typical use would be to retrieve some secure auth token.

#### Parameters

auth | a GsAuth |
key | a string |

#### Returns

A string value, or `NULL` for not found

### gs_auth_add_metadata ()

    void
    gs_auth_add_metadata (GsAuth *auth,
                          const gchar *key,
                          const gchar *value);

Adds metadata to the authentication object. It is left for the the plugin to use this method as required, but a typical use would be to store some secure auth token.

#### Parameters

auth | a GsAuth |
key | a string |
value | a string |

### gs_auth_store_load ()

    gboolean
    gs_auth_store_load (GsAuth *auth,
                        GsAuthStoreFlags flags,
                        GCancellable *cancellable,
                        GError **error);

Loads authentication tokens from disk in a secure way. By default only the username and password are loaded, but they are not overwritten if already set.

If additional tokens are required to be loaded you must first tell the GsAuth instance what metadata to load. This can be done using: `gs_auth_add_metadata("additional-secret-key-name",NULL)`

This function is expected to be called from `gs_plugin_setup()`.

#### Parameters

auth | a GsAuth |
flags | some GsAuthStoreFlags, e.g. `GS_AUTH_STORE_FLAG_USERNAME` |
cancellable | a GCancellable or `NULL` |
error | a GError or `NULL` |

#### Returns

`TRUE` if the tokens were loaded correctly.

### gs_auth_store_save ()

    gboolean
    gs_auth_store_save (GsAuth *auth,
                        GsAuthStoreFlags flags,
                        GCancellable *cancellable,
                        GError **error);

Saves the username, password and all added metadata to disk in a secure way.

This function is expected to be called from `gs_plugin_setup()`.

#### Parameters

auth | a GsAuth |
flags | some GsAuthStoreFlags, e.g. `GS_AUTH_STORE_FLAG_USERNAME` |
cancellable | a GCancellable or `NULL` |
error | a GError or `NULL` |

#### Returns

`TRUE` if the tokens were all saved correctly.

### gs_auth_store_clear ()

    gboolean
    gs_auth_store_clear (GsAuth *auth,
                         GsAuthStoreFlags flags,
                         GCancellable *cancellable,
                         GError **error);

## Types and Values

### GS_TYPE_AUTH

    #define GS_TYPE_AUTH (gs_auth_get_type ())

### enum GsAuthFlags

The flags for the auth.

#### Members

GS_AUTH_FLAG_NONE | No special flags set |
GS_AUTH_FLAG_VALID | Authorisation is valid |
GS_AUTH_FLAG_REMEMBER | Remember this authentication if possible |

### enum GsAuthStoreFlags

The flags used when loading or saving the authentication to disk.

#### Members

GS_AUTH_STORE_FLAG_NONE | No special flags set |
GS_AUTH_STORE_FLAG_USERNAME | Load or save the username |
GS_AUTH_STORE_FLAG_PASSWORD | Load or save the password |
GS_AUTH_STORE_FLAG_METADATA | Load or save any metadata |

### GsAuth

    typedef struct _GsAuth GsAuth;