gio/gtlspassword.c

   1 /* GIO - GLib Input, Output and Streaming Library
   2  *
   3  * Copyright (C) 2011 Collabora, Ltd.
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General
  16  * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  17  *
  18  * Author: Stef Walter <stefw@collabora.co.uk>
  19  */
  20
  21 #include "config.h"
  22 #include "glib.h"
  23 #include "glibintl.h"
  24
  25 #include "gioenumtypes.h"
  26 #include "gtlspassword.h"
  27
  28 #include <string.h>
  29
  30 /**
  31  * SECTION:gtlspassword
  32  * @title: GTlsPassword
  33  * @short_description: TLS Passwords for prompting
  34  * @include: gio/gio.h
  35  *
  36  * Holds a password used in TLS.
  37  */
  38
  39 /**
  40  * GTlsPassword:
  41  *
  42  * An abstract interface representing a password used in TLS. Often used in
  43  * user interaction such as unlocking a key storage token.
  44  *
  45  * Since: 2.30
  46  */
  47
  48 enum
  49 {
  50   PROP_0,
  51   PROP_FLAGS,
  52   PROP_DESCRIPTION,
  53   PROP_WARNING
  54 };
  55
  56 struct _GTlsPasswordPrivate
  57 {
  58   guchar *value;
  59   gsize length;
  60   GDestroyNotify destroy;
  61   GTlsPasswordFlags flags;
  62   gchar *description;
  63   gchar *warning;
  64 };
  65
  66 G_DEFINE_TYPE_WITH_PRIVATE (GTlsPassword, g_tls_password, G_TYPE_OBJECT)
  67
  68 static void
  69 g_tls_password_init (GTlsPassword *password)
  70 {
  71   password->priv = g_tls_password_get_instance_private (password);
  72 }
  73
  74 static const guchar *
  75 g_tls_password_real_get_value (GTlsPassword  *password,
  76                                gsize         *length)
  77 {
  78   if (length)
  79     *length = password->priv->length;
  80   return password->priv->value;
  81 }
  82
  83 static void
  84 g_tls_password_real_set_value (GTlsPassword   *password,
  85                                guchar         *value,
  86                                gssize          length,
  87                                GDestroyNotify  destroy)
  88 {
  89   if (password->priv->destroy)
  90       (password->priv->destroy) (password->priv->value);
  91   password->priv->destroy = NULL;
  92   password->priv->value = NULL;
  93   password->priv->length = 0;
  94
  95   if (length < 0)
  96     length = strlen ((gchar*) value);
  97
  98   password->priv->value = value;
  99   password->priv->length = length;
 100   password->priv->destroy = destroy;
 101 }
 102
 103 static const gchar*
 104 g_tls_password_real_get_default_warning (GTlsPassword  *password)
 105 {
 106   GTlsPasswordFlags flags;
 107
 108   flags = g_tls_password_get_flags (password);
 109
 110   if (flags & G_TLS_PASSWORD_FINAL_TRY)
 111     return _("This is the last chance to enter the password correctly before your access is locked out.");
 112   if (flags & G_TLS_PASSWORD_MANY_TRIES)
 113     return _("Several password entered have been incorrect, and your access will be locked out after further failures.");
 114   if (flags & G_TLS_PASSWORD_RETRY)
 115     return _("The password entered is incorrect.");
 116
 117   return NULL;
 118 }
 119
 120 static void
 121 g_tls_password_get_property (GObject    *object,
 122                              guint       prop_id,
 123                              GValue     *value,
 124                              GParamSpec *pspec)
 125 {
 126   GTlsPassword *password = G_TLS_PASSWORD (object);
 127
 128   switch (prop_id)
 129     {
 130     case PROP_FLAGS:
 131       g_value_set_flags (value, g_tls_password_get_flags (password));
 132       break;
 133     case PROP_WARNING:
 134       g_value_set_string (value, g_tls_password_get_warning (password));
 135       break;
 136     case PROP_DESCRIPTION:
 137       g_value_set_string (value, g_tls_password_get_description (password));
 138       break;
 139     default:
 140       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 141       break;
 142     }
 143 }
 144
 145 static void
 146 g_tls_password_set_property (GObject      *object,
 147                              guint         prop_id,
 148                              const GValue *value,
 149                              GParamSpec   *pspec)
 150 {
 151   GTlsPassword *password = G_TLS_PASSWORD (object);
 152
 153   switch (prop_id)
 154     {
 155     case PROP_FLAGS:
 156       g_tls_password_set_flags (password, g_value_get_flags (value));
 157       break;
 158     case PROP_WARNING:
 159       g_tls_password_set_warning (password, g_value_get_string (value));
 160       break;
 161     case PROP_DESCRIPTION:
 162       g_tls_password_set_description (password, g_value_get_string (value));
 163       break;
 164     default:
 165       G_OBJECT_WARN_INVALID_PROPERTY_ID (object, prop_id, pspec);
 166       break;
 167     }
 168 }
 169
 170 static void
 171 g_tls_password_finalize (GObject *object)
 172 {
 173   GTlsPassword *password = G_TLS_PASSWORD (object);
 174
 175   g_tls_password_real_set_value (password, NULL, 0, NULL);
 176   g_free (password->priv->warning);
 177   g_free (password->priv->description);
 178
 179   G_OBJECT_CLASS (g_tls_password_parent_class)->finalize (object);
 180 }
 181
 182 static void
 183 g_tls_password_class_init (GTlsPasswordClass *klass)
 184 {
 185   GObjectClass *gobject_class = G_OBJECT_CLASS (klass);
 186
 187   klass->get_value = g_tls_password_real_get_value;
 188   klass->set_value = g_tls_password_real_set_value;
 189   klass->get_default_warning = g_tls_password_real_get_default_warning;
 190
 191   gobject_class->get_property = g_tls_password_get_property;
 192   gobject_class->set_property = g_tls_password_set_property;
 193   gobject_class->finalize = g_tls_password_finalize;
 194
 195   g_object_class_install_property (gobject_class, PROP_FLAGS,
 196                                    g_param_spec_flags ("flags",
 197                                                        P_("Flags"),
 198                                                        P_("Flags about the password"),
 199                                                        G_TYPE_TLS_PASSWORD_FLAGS,
 200                                                        G_TLS_PASSWORD_NONE,
 201                                                        G_PARAM_READWRITE |
 202                                                        G_PARAM_STATIC_STRINGS));
 203
 204   g_object_class_install_property (gobject_class, PROP_DESCRIPTION,
 205                                    g_param_spec_string ("description",
 206                                                         P_("Description"),
 207                                                         P_("Description of what the password is for"),
 208                                                         NULL,
 209                                                         G_PARAM_READWRITE |
 210                                                         G_PARAM_STATIC_STRINGS));
 211
 212   g_object_class_install_property (gobject_class, PROP_WARNING,
 213                                    g_param_spec_string ("warning",
 214                                                         P_("Warning"),
 215                                                         P_("Warning about the password"),
 216                                                         NULL,
 217                                                         G_PARAM_READWRITE |
 218                                                         G_PARAM_STATIC_STRINGS));
 219
 220 }
 221
 222 /**
 223  * g_tls_password_new:
 224  * @flags: the password flags
 225  * @description: description of what the password is for
 226  *
 227  * Create a new #GTlsPassword object.
 228  *
 229  * Returns: (transfer full): The newly allocated password object
 230  */
 231 GTlsPassword *
 232 g_tls_password_new (GTlsPasswordFlags  flags,
 233                     const gchar       *description)
 234 {
 235   return g_object_new (G_TYPE_TLS_PASSWORD,
 236                        "flags", flags,
 237                        "description", description,
 238                        NULL);
 239 }
 240
 241 /**
 242  * g_tls_password_get_value:
 243  * @password: a #GTlsPassword object
 244  * @length: (nullable): location to place the length of the password.
 245  *
 246  * Get the password value. If @length is not %NULL then it will be
 247  * filled in with the length of the password value. (Note that the
 248  * password value is not nul-terminated, so you can only pass %NULL
 249  * for @length in contexts where you know the password will have a
 250  * certain fixed length.)
 251  *
 252  * Returns: The password value (owned by the password object).
 253  *
 254  * Since: 2.30
 255  */
 256 const guchar *
 257 g_tls_password_get_value (GTlsPassword  *password,
 258                           gsize         *length)
 259 {
 260   g_return_val_if_fail (G_IS_TLS_PASSWORD (password), NULL);
 261   return G_TLS_PASSWORD_GET_CLASS (password)->get_value (password, length);
 262 }
 263
 264 /**
 265  * g_tls_password_set_value:
 266  * @password: a #GTlsPassword object
 267  * @value: the new password value
 268  * @length: the length of the password, or -1
 269  *
 270  * Set the value for this password. The @value will be copied by the password
 271  * object.
 272  *
 273  * Specify the @length, for a non-nul-terminated password. Pass -1 as
 274  * @length if using a nul-terminated password, and @length will be
 275  * calculated automatically. (Note that the terminating nul is not
 276  * considered part of the password in this case.)
 277  *
 278  * Since: 2.30
 279  */
 280 void
 281 g_tls_password_set_value (GTlsPassword  *password,
 282                           const guchar  *value,
 283                           gssize         length)
 284 {
 285   g_return_if_fail (G_IS_TLS_PASSWORD (password));
 286
 287   if (length < 0)
 288     length = strlen ((gchar *)value);
 289
 290   g_tls_password_set_value_full (password, g_memdup (value, length), length, g_free);
 291 }
 292
 293 /**
 294  * g_tls_password_set_value_full:
 295  * @password: a #GTlsPassword object
 296  * @value: the value for the password
 297  * @length: the length of the password, or -1
 298  * @destroy: (nullable): a function to use to free the password.
 299  *
 300  * Provide the value for this password.
 301  *
 302  * The @value will be owned by the password object, and later freed using
 303  * the @destroy function callback.
 304  *
 305  * Specify the @length, for a non-nul-terminated password. Pass -1 as
 306  * @length if using a nul-terminated password, and @length will be
 307  * calculated automatically. (Note that the terminating nul is not
 308  * considered part of the password in this case.)
 309  *
 310  * Virtual: set_value
 311  * Since: 2.30
 312  */
 313 void
 314 g_tls_password_set_value_full (GTlsPassword   *password,
 315                                guchar         *value,
 316                                gssize          length,
 317                                GDestroyNotify  destroy)
 318 {
 319   g_return_if_fail (G_IS_TLS_PASSWORD (password));
 320   G_TLS_PASSWORD_GET_CLASS (password)->set_value (password, value,
 321                                                   length, destroy);
 322 }
 323
 324 /**
 325  * g_tls_password_get_flags:
 326  * @password: a #GTlsPassword object
 327  *
 328  * Get flags about the password.
 329  *
 330  * Returns: The flags about the password.
 331  *
 332  * Since: 2.30
 333  */
 334 GTlsPasswordFlags
 335 g_tls_password_get_flags (GTlsPassword *password)
 336 {
 337   g_return_val_if_fail (G_IS_TLS_PASSWORD (password), G_TLS_PASSWORD_NONE);
 338   return password->priv->flags;
 339 }
 340
 341 /**
 342  * g_tls_password_set_flags:
 343  * @password: a #GTlsPassword object
 344  * @flags: The flags about the password
 345  *
 346  * Set flags about the password.
 347  *
 348  * Since: 2.30
 349  */
 350 void
 351 g_tls_password_set_flags (GTlsPassword      *password,
 352                           GTlsPasswordFlags  flags)
 353 {
 354   g_return_if_fail (G_IS_TLS_PASSWORD (password));
 355
 356   password->priv->flags = flags;
 357
 358   g_object_notify (G_OBJECT (password), "flags");
 359 }
 360
 361 /**
 362  * g_tls_password_get_description:
 363  * @password: a #GTlsPassword object
 364  *
 365  * Get a description string about what the password will be used for.
 366  *
 367  * Returns: The description of the password.
 368  *
 369  * Since: 2.30
 370  */
 371 const gchar*
 372 g_tls_password_get_description (GTlsPassword *password)
 373 {
 374   g_return_val_if_fail (G_IS_TLS_PASSWORD (password), NULL);
 375   return password->priv->description;
 376 }
 377
 378 /**
 379  * g_tls_password_set_description:
 380  * @password: a #GTlsPassword object
 381  * @description: The description of the password
 382  *
 383  * Set a description string about what the password will be used for.
 384  *
 385  * Since: 2.30
 386  */
 387 void
 388 g_tls_password_set_description (GTlsPassword      *password,
 389                                 const gchar       *description)
 390 {
 391   gchar *copy;
 392
 393   g_return_if_fail (G_IS_TLS_PASSWORD (password));
 394
 395   copy = g_strdup (description);
 396   g_free (password->priv->description);
 397   password->priv->description = copy;
 398
 399   g_object_notify (G_OBJECT (password), "description");
 400 }
 401
 402 /**
 403  * g_tls_password_get_warning:
 404  * @password: a #GTlsPassword object
 405  *
 406  * Get a user readable translated warning. Usually this warning is a
 407  * representation of the password flags returned from
 408  * g_tls_password_get_flags().
 409  *
 410  * Returns: The warning.
 411  *
 412  * Since: 2.30
 413  */
 414 const gchar *
 415 g_tls_password_get_warning (GTlsPassword      *password)
 416 {
 417   g_return_val_if_fail (G_IS_TLS_PASSWORD (password), NULL);
 418
 419   if (password->priv->warning == NULL)
 420     return G_TLS_PASSWORD_GET_CLASS (password)->get_default_warning (password);
 421
 422   return password->priv->warning;
 423 }
 424
 425 /**
 426  * g_tls_password_set_warning:
 427  * @password: a #GTlsPassword object
 428  * @warning: The user readable warning
 429  *
 430  * Set a user readable translated warning. Usually this warning is a
 431  * representation of the password flags returned from
 432  * g_tls_password_get_flags().
 433  *
 434  * Since: 2.30
 435  */
 436 void
 437 g_tls_password_set_warning (GTlsPassword      *password,
 438                             const gchar       *warning)
 439 {
 440   gchar *copy;
 441
 442   g_return_if_fail (G_IS_TLS_PASSWORD (password));
 443
 444   copy = g_strdup (warning);
 445   g_free (password->priv->warning);
 446   password->priv->warning = copy;
 447
 448   g_object_notify (G_OBJECT (password), "warning");
 449 }