NMACertChooser

NMACertChooser

Properties

guint flags Write / Construct Only
gchar * title Write / Construct Only

Signals

GError* cert-password-validate Run Last
GError* cert-validate Run Last
void changed No Recursion
GError* key-password-validate Run Last
GError* key-validate Run Last

Types and Values

Object Hierarchy

    GObject
    ╰── GInitiallyUnowned
        ╰── GtkWidget
            ╰── GtkContainer
                ╰── GtkGrid
                    ╰── NMACertChooser

Description

Certificate chooser allows for selection of a certificate or various schemes optionally accompanied with a key and passwords or PIN.

The widgets that implement this interface may allow selecting the certificates from various sources such as files or cryptographic tokens.

Functions

nma_cert_chooser_set_cert ()

void
nma_cert_chooser_set_cert (NMACertChooser *cert_chooser,
                           const gchar *value,
                           NMSetting8021xCKScheme scheme);

Sets the certificate location for the chooser button.

Parameters

cert_chooser

certificate chooser button instance

 

value

the path or URI of a certificate

 

scheme

the scheme of the certificate path

 

Since: 1.8.0


nma_cert_chooser_set_cert_uri ()

void
nma_cert_chooser_set_cert_uri (NMACertChooser *cert_chooser,
                               const gchar *uri);

Sets the certificate URI for the chooser button.

Parameters

cert_chooser

certificate chooser button instance

 

uri

the path or URI of a certificate

 

Since: 1.8.0


nma_cert_chooser_get_cert ()

gchar *
nma_cert_chooser_get_cert (NMACertChooser *cert_chooser,
                           NMSetting8021xCKScheme *scheme);

Gets the real certificate location from the chooser button along with the scheme.

Parameters

cert_chooser

certificate chooser button instance

 

scheme

the scheme of the returned certificate path.

[out]

Returns

the certificate path

Since: 1.8.0


nma_cert_chooser_get_cert_uri ()

gchar *
nma_cert_chooser_get_cert_uri (NMACertChooser *cert_chooser);

Gets the real certificate URI from the chooser button along with the scheme.

Parameters

cert_chooser

certificate chooser button instance

 

Returns

the certificate URI

Since: 1.8.0


nma_cert_chooser_set_cert_password ()

void
nma_cert_chooser_set_cert_password (NMACertChooser *cert_chooser,
                                    const gchar *password);

Sets the password or a PIN that might be required to access the certificate.

Parameters

cert_chooser

certificate chooser button instance

 

password

the certificate PIN or password

 

Since: 1.8.0


nma_cert_chooser_get_cert_password ()

const gchar *
nma_cert_chooser_get_cert_password (NMACertChooser *cert_chooser);

Obtains the password or a PIN that was be required to access the certificate.

Parameters

cert_chooser

certificate chooser button instance

 

Returns

the certificate PIN or password

Since: 1.8.0


nma_cert_chooser_set_key ()

void
nma_cert_chooser_set_key (NMACertChooser *cert_chooser,
                          const gchar *value,
                          NMSetting8021xCKScheme scheme);

Sets the key location for the chooser button.

Parameters

cert_chooser

certificate chooser button instance

 

value

the path or URI of a key

 

scheme

the scheme of the key path

 

Since: 1.8.0


nma_cert_chooser_set_key_uri ()

void
nma_cert_chooser_set_key_uri (NMACertChooser *cert_chooser,
                              const gchar *uri);

Sets the key URI for the chooser button.

Parameters

cert_chooser

certificate chooser button instance

 

uri

the URI of a key

 

Since: 1.8.0


nma_cert_chooser_get_key ()

gchar *
nma_cert_chooser_get_key (NMACertChooser *cert_chooser,
                          NMSetting8021xCKScheme *scheme);

Gets the real key location from the chooser button along with the scheme.

Parameters

cert_chooser

certificate chooser button instance

 

scheme

the scheme of the returned key path.

[out]

Returns

the key path

Since: 1.8.0


nma_cert_chooser_get_key_uri ()

gchar *
nma_cert_chooser_get_key_uri (NMACertChooser *cert_chooser);

Gets the real key URI from the chooser button along with the scheme.

Parameters

cert_chooser

certificate chooser button instance

 

Returns

the key URI

Since: 1.8.0


nma_cert_chooser_set_key_password ()

void
nma_cert_chooser_set_key_password (NMACertChooser *cert_chooser,
                                   const gchar *password);

Sets the password or a PIN that might be required to access the key.

Parameters

cert_chooser

certificate chooser button instance

 

password

the key PIN or password

 

Since: 1.8.0


nma_cert_chooser_get_key_password ()

const gchar *
nma_cert_chooser_get_key_password (NMACertChooser *cert_chooser);

Obtains the password or a PIN that was be required to access the key.

Parameters

cert_chooser

certificate chooser button instance

 

Returns

the key PIN or password

Since: 1.8.0


nma_cert_chooser_new ()

GtkWidget *
nma_cert_chooser_new (const gchar *title,
                      NMACertChooserFlags flags);

Constructs the button that is capable of selecting a certificate and a key.

Parameters

title

title of the certificate chooser dialog

 

flags

the flags that configure the capabilities of the button

 

Returns

the certificate chooser button instance.

[transfer full]

Since: 1.8.0


nma_cert_chooser_add_to_size_group ()

void
nma_cert_chooser_add_to_size_group (NMACertChooser *cert_chooser,
                                    GtkSizeGroup *group);

Adds the labels to the specified size group so that they are aligned nicely with other entries in a form.

It is expected that the NMACertChooser is a GtkGrid with two columns with the labels in the first one.

Parameters

cert_chooser

certificate chooser button instance

 

group

a size group

 

Since: 1.8.0


nma_cert_chooser_validate ()

gboolean
nma_cert_chooser_validate (NMACertChooser *cert_chooser,
                           GError **error);

Validates whether the chosen values make sense. The users can do further validation by subscribing to the "*-changed" signals and returning an error themselves.

Parameters

cert_chooser

certificate chooser button instance

 

error

error return location

 

Returns

TRUE if validation passes, FALSE otherwise

Since: 1.8.0


nma_cert_chooser_setup_cert_password_storage ()

void
nma_cert_chooser_setup_cert_password_storage
                               (NMACertChooser *cert_chooser,
                                NMSettingSecretFlags initial_flags,
                                NMSetting *setting,
                                const char *password_flags_name,
                                gboolean with_not_required,
                                gboolean ask_mode);

This method basically calls nma_utils_setup_password_storage() on the certificate password entry, in case one is present.

Parameters

cert_chooser

certificate chooser button instance

 

initial_flags

initial secret flags to setup password menu from

 

setting

NMSetting containing the password, or NULL

 

password_flags_name

name of the secret flags (like psk-flags), or NULL

 

with_not_required

whether to include "Not required" menu item

 

ask_mode

TRUE if the entry is shown in ASK mode

 

Since: 1.8.0


nma_cert_chooser_update_cert_password_storage ()

void
nma_cert_chooser_update_cert_password_storage
                               (NMACertChooser *cert_chooser,
                                NMSettingSecretFlags secret_flags,
                                NMSetting *setting,
                                const char *password_flags_name);

This method basically calls nma_utils_update_password_storage() on the certificate password entry, in case one is present.

Parameters

cert_chooser

certificate chooser button instance

 

secret_flags

secret flags to set

 

setting

NMSetting containing the password, or NULL

 

password_flags_name

name of the secret flags (like psk-flags), or NULL

 

Since: 1.8.0


nma_cert_chooser_get_cert_password_flags ()

NMSettingSecretFlags
nma_cert_chooser_get_cert_password_flags
                               (NMACertChooser *cert_chooser);

Returns secret flags corresponding to the certificate password if one is present. The chooser would typically call into nma_utils_menu_to_secret_flags() for the certificate password entry.

Parameters

cert_chooser

certificate chooser button instance

 

Returns

secret flags corresponding to the certificate password

Since: 1.8.0


nma_cert_chooser_setup_key_password_storage ()

void
nma_cert_chooser_setup_key_password_storage
                               (NMACertChooser *cert_chooser,
                                NMSettingSecretFlags initial_flags,
                                NMSetting *setting,
                                const char *password_flags_name,
                                gboolean with_not_required,
                                gboolean ask_mode);

This method basically calls nma_utils_setup_password_storage() on the key password entry, in case one is present.

Parameters

cert_chooser

certificate chooser button instance

 

initial_flags

initial secret flags to setup password menu from

 

setting

NMSetting containing the password, or NULL

 

password_flags_name

name of the secret flags (like psk-flags), or NULL

 

with_not_required

whether to include "Not required" menu item

 

ask_mode

TRUE if the entry is shown in ASK mode

 

Since: 1.8.0


nma_cert_chooser_update_key_password_storage ()

void
nma_cert_chooser_update_key_password_storage
                               (NMACertChooser *cert_chooser,
                                NMSettingSecretFlags secret_flags,
                                NMSetting *setting,
                                const char *password_flags_name);

This method basically calls nma_utils_update_password_storage() on the key password entry, in case one is present.

Parameters

cert_chooser

certificate chooser button instance

 

secret_flags

secret flags to set

 

setting

NMSetting containing the password, or NULL

 

password_flags_name

name of the secret flags (like psk-flags), or NULL

 

Since: 1.8.0


nma_cert_chooser_get_key_password_flags ()

NMSettingSecretFlags
nma_cert_chooser_get_key_password_flags
                               (NMACertChooser *cert_chooser);

Returns secret flags corresponding to the key password if one is present. The chooser would typically call into nma_utils_menu_to_secret_flags() for the key password entry.

Parameters

cert_chooser

certificate chooser button instance

 

Returns

secret flags corresponding to the key password

Since: 1.8.0

Types and Values

enum NMACertChooserFlags

Flags that controls what is the certificate chooser button able to pick. Currently only local files are supported, but might be extended to use URIs, such as PKCS#11 certificate URIs in future as well.

Members

NMA_CERT_CHOOSER_FLAG_NONE

No flags

 

NMA_CERT_CHOOSER_FLAG_CERT

Only pick a certificate, not a key

 

NMA_CERT_CHOOSER_FLAG_PASSWORDS

Hide all controls but the secrets entries

 

NMA_CERT_CHOOSER_FLAG_PEM

Ensure the chooser only selects regular PEM files

 

Since: 1.8.0

Property Details

The “flags” property

  “flags”                    guint

Certificate Chooser Flags.

Flags: Write / Construct Only

Allowed values: <= 7

Default value: 0


The “title” property

  “title”                    gchar *

Certificate Chooser Title.

Flags: Write / Construct Only

Default value: NULL

Signal Details

The “cert-password-validate” signal

GError*
user_function (NMACertChooser *arg0,
               gpointer        user_data)

Emitted when the certificate password needs validation. The handlers can indicate that the password is invalid by returning an error, which blocks further signal processing and causes a call to nma_cert_chooser_validate() to fail.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.8.0


The “cert-validate” signal

GError*
user_function (NMACertChooser *arg0,
               gpointer        user_data)

Emitted when the certificate needs validation. The handlers can indicate that the certificate is invalid by returning an error, which blocks further signal processing and causes a call to nma_cert_chooser_validate() to fail.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.8.0


The “changed” signal

void
user_function (NMACertChooser *arg0,
               gpointer        user_data)

Emitted when anything changes in the certificate chooser, be it a certificate, a key or associated passwords.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: No Recursion

Since: 1.8.0


The “key-password-validate” signal

GError*
user_function (NMACertChooser *arg0,
               gpointer        user_data)

Emitted when the key password needs validation. The handlers can indicate that the password is invalid by returning an error, which blocks further signal processing and causes a call to nma_cert_chooser_validate() to fail.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.8.0


The “key-validate” signal

GError*
user_function (NMACertChooser *arg0,
               gpointer        user_data)

Emitted when the key needs validation. The handlers can indicate that the key is invalid by returning an error, which blocks further signal processing and causes a call to nma_cert_chooser_validate() to fail.

Parameters

user_data

user data set when the signal handler was connected.

 

Flags: Run Last

Since: 1.8.0