GTlsPassword: GIO Reference Manual

## GTlsPassword GTlsPassword — TLS Passwords for prompting |

## Functions

GTlsPassword * | g_tls_password_new ()
const guchar * | g_tls_password_get_value ()
void | g_tls_password_set_value ()
void | g_tls_password_set_value_full ()
const gchar * | g_tls_password_get_description ()
void | g_tls_password_set_description ()
GTlsPasswordFlags | g_tls_password_get_flags ()
void | g_tls_password_set_flags ()
const gchar * | g_tls_password_get_warning ()
void | g_tls_password_set_warning ()

## Properties

char * | description | Read / Write
GTlsPasswordFlags | flags | Read / Write
char * | warning | Read / Write

## Types and Values

| GTlsPassword
struct | GTlsPasswordClass
enum | GTlsPasswordFlags

## Object Hierarchy

        GFlags
        ╰── GTlsPasswordFlags
        GObject
        ╰── GTlsPassword

## Includes

    #include <gio/gio.h>

## Description

Holds a password used in TLS.

## Functions

### g_tls_password_new ()

    GTlsPassword *
    g_tls_password_new (GTlsPasswordFlags flags,
                        const gchar *description);

Create a new GTlsPassword object.

#### Parameters

flags | the password flags |
description | description of what the password is for |

#### Returns

The newly allocated password object.

[transfer full]

### g_tls_password_get_value ()

    const guchar *
    g_tls_password_get_value (GTlsPassword *password,
                              gsize *length);

Get the password value. If `length` is not `NULL` then it will be filled in with the length of the password value. (Note that the password value is not nul-terminated, so you can only pass `NULL` for `length` in contexts where you know the password will have a certain fixed length.)

[virtual get_value]

#### Parameters

password | a GTlsPassword object |
length | location to place the length of the password. | [optional]

#### Returns

The password value (owned by the password object).

[array length=length]

Since: 2.30

### g_tls_password_set_value ()

    void
    g_tls_password_set_value (GTlsPassword *password,
                              const guchar *value,
                              gssize length);

Set the value for this password. The `value` will be copied by the password object.

Specify the `length` , for a non-nul-terminated password. Pass -1 as `length` if using a nul-terminated password, and `length` will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.)

#### Parameters

password | a GTlsPassword object |
value | the new password value. | [array length=length]
length | the length of the password, or -1 |

Since: 2.30

### g_tls_password_set_value_full ()

    void
    g_tls_password_set_value_full (GTlsPassword *password,
                                   guchar *value,
                                   gssize length,
                                   GDestroyNotify destroy);

Provide the value for this password.

The `value` will be owned by the password object, and later freed using the `destroy` function callback.

Specify the `length` , for a non-nul-terminated password. Pass -1 as `length` if using a nul-terminated password, and `length` will be calculated automatically. (Note that the terminating nul is not considered part of the password in this case.)

Virtual: set_value

#### Parameters

password | a GTlsPassword object |
value | the value for the password. | [array length=length]
length | the length of the password, or -1 |
destroy | a function to use to free the password. | [nullable]

Since: 2.30

### g_tls_password_get_description ()

    const gchar *
    g_tls_password_get_description (GTlsPassword *password);

Get a description string about what the password will be used for.

#### Parameters

password | a GTlsPassword object |

#### Returns

The description of the password.

Since: 2.30

### g_tls_password_set_description ()

    void
    g_tls_password_set_description (GTlsPassword *password,
                                    const gchar *description);

Set a description string about what the password will be used for.

#### Parameters

password | a GTlsPassword object |
description | The description of the password |

Since: 2.30

### g_tls_password_get_flags ()

    GTlsPasswordFlags
    g_tls_password_get_flags (GTlsPassword *password);

Get flags about the password.

#### Parameters

password | a GTlsPassword object |

#### Returns

The flags about the password.

Since: 2.30

### g_tls_password_set_flags ()

    void
    g_tls_password_set_flags (GTlsPassword *password,
                              GTlsPasswordFlags flags);

Set flags about the password.

#### Parameters

password | a GTlsPassword object |
flags | The flags about the password |

Since: 2.30

### g_tls_password_get_warning ()

    const gchar *
    g_tls_password_get_warning (GTlsPassword *password);

Get a user readable translated warning. Usually this warning is a representation of the password flags returned from `g_tls_password_get_flags()`.

#### Parameters

password | a GTlsPassword object |

#### Returns

The warning.

Since: 2.30

### g_tls_password_set_warning ()

    void
    g_tls_password_set_warning (GTlsPassword *password,
                                const gchar *warning);

Set a user readable translated warning. Usually this warning is a representation of the password flags returned from `g_tls_password_get_flags()`.

#### Parameters

password | a GTlsPassword object |
warning | The user readable warning |

Since: 2.30

## Types and Values

### GTlsPassword

    typedef struct _GTlsPassword GTlsPassword;

An abstract interface representing a password used in TLS. Often used in user interaction such as unlocking a key storage token.

Since: 2.30

### struct GTlsPasswordClass

    struct GTlsPasswordClass {
      GObjectClass parent_class;

      /* methods */

      const guchar *    ( *get_value)            (GTlsPassword  *password,
                                                  gsize         *length);

      void              ( *set_value)            (GTlsPassword  *password,
                                                  guchar        *value,
                                                  gssize         length,
                                                  GDestroyNotify destroy);

      const gchar*      ( *get_default_warning)  (GTlsPassword  *password);
    };

Class structure for GTlsPassword.

#### Members

`get_value` () | virtual method for `g_tls_password_get_value()` |
`set_value` () | virtual method for `g_tls_password_set_value()` |
`get_default_warning` () | virtual method for `g_tls_password_get_warning()` if no value has been set using `g_tls_password_set_warning()` |

### enum GTlsPasswordFlags

Various flags for the password.

#### Members

G_TLS_PASSWORD_NONE | No flags |
G_TLS_PASSWORD_RETRY | The password was wrong, and the user should retry. |
G_TLS_PASSWORD_MANY_TRIES | Hint to the user that the password has been wrong many times, and the user may not have many chances left. |
G_TLS_PASSWORD_FINAL_TRY | Hint to the user that this is the last try to get this password right. |
G_TLS_PASSWORD_PKCS11_USER | For PKCS 11, the user PIN is required. Since: 2.70. |
G_TLS_PASSWORD_PKCS11_SECURITY_OFFICER | For PKCS 11, the security officer PIN is required. Since: 2.70. |
G_TLS_PASSWORD_PKCS11_CONTEXT_SPECIFIC | For PKCS 11, the context-specific PIN is required. Since: 2.70. |

Since: 2.30

## Property Details

### The `“description”` property

      “description”              char *

Description of what the password is for.

Owner: GTlsPassword

Flags: Read / Write

Default value: NULL

### The `“flags”` property

      “flags”                    GTlsPasswordFlags

Flags about the password.

Owner: GTlsPassword

Flags: Read / Write

### The `“warning”` property

      “warning”                  char *

Warning about the password.

Owner: GTlsPassword

Flags: Read / Write

Default value: NULL