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