NMACertChooser: libnma Reference Manual

## NMACertChooser NMACertChooser |

## Functions

void | nma_cert_chooser_set_cert ()
void | nma_cert_chooser_set_cert_uri ()
gchar * | nma_cert_chooser_get_cert ()
gchar * | nma_cert_chooser_get_cert_uri ()
void | nma_cert_chooser_set_cert_password ()
const gchar * | nma_cert_chooser_get_cert_password ()
void | nma_cert_chooser_set_key ()
void | nma_cert_chooser_set_key_uri ()
gchar * | nma_cert_chooser_get_key ()
gchar * | nma_cert_chooser_get_key_uri ()
void | nma_cert_chooser_set_key_password ()
const gchar * | nma_cert_chooser_get_key_password ()
GtkWidget * | nma_cert_chooser_new ()
void | nma_cert_chooser_add_to_size_group ()
gboolean | nma_cert_chooser_validate ()
void | nma_cert_chooser_setup_cert_password_storage ()
void | nma_cert_chooser_update_cert_password_storage ()
NMSettingSecretFlags | nma_cert_chooser_get_cert_password_flags ()
void | nma_cert_chooser_setup_key_password_storage ()
void | nma_cert_chooser_update_key_password_storage ()
NMSettingSecretFlags | nma_cert_chooser_get_key_password_flags ()

## Properties

guint | flags | Write / Construct Only
char * | 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

enum | NMACertChooserFlags

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

[transfer full][nullable]

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.

[transfer full][nullable]

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.

[transfer full][nullable]

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.

[transfer full][nullable]

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 |
NMA_CERT_CHOOSER_FLAG_NO_PASSWORDS | Do not show password entries (Since: 1.8.34) |

Since: 1.8.0

## Property Details

### The `“flags”` property

      “flags”                    guint

Certificate Chooser Flags.

Owner: NMACertChooser

Flags: Write / Construct Only

Allowed values: <= 15

Default value: 0

### The `“title”` property

      “title”                    char *

Certificate Chooser Title.

Owner: NMACertChooser

Flags: Write / Construct Only

Default value: NULL

## Signal Details

### The `“cert-password-validate”` signal

    GError*
    user_function (NMACertChooser *nmacertchooser,
                   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 *nmacertchooser,
                   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 *nmacertchooser,
                   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 *nmacertchooser,
                   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 *nmacertchooser,
                   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