kde3support/kdeui/k3passworddialog.h

   1 // vi: ts=8 sts=4 sw=4
   2 /* This file is part of the KDE libraries
   3    Copyright (C) 1998 Pietro Iglio <iglio@fub.it>
   4    Copyright (C) 1999,2000 Geert Jansen <jansen@kde.org>
   5    Copyright (C) 2004,2005 Andrew Coles <andrew_coles@yahoo.co.uk>
   6
   7    This library is free software; you can redistribute it and/or
   8    modify it under the terms of the GNU Library General Public
   9    License version 2 as published by the Free Software Foundation.
  10
  11    This library is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14    Library General Public License for more details.
  15
  16    You should have received a copy of the GNU Library General Public License
  17    along with this library; see the file COPYING.LIB.  If not, write to
  18    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19    Boston, MA 02110-1301, USA.
  20 */
  21 #ifndef K3PASSWORDDIALOG_H
  22 #define K3PASSWORDDIALOG_H
  23
  24 #include <kde3support_export.h>
  25 #include <kdialog.h>
  26
  27 #include <QtGui/QLineEdit>
  28
  29 class QLabel;
  30 class QGridLayout;
  31 class QWidget;
  32
  33 /**
  34  * @short A safe password input widget.
  35  * @author Geert Jansen <geertj@kde.org>
  36  *
  37  * The widget uses the user's global "echo mode" setting.
  38  * @deprecated use KLineEdit with KLineEdit::setPasswordMode(true)
  39  */
  40
  41 class KDE3SUPPORT_EXPORT K3PasswordEdit
  42     : public QLineEdit
  43 {
  44     Q_OBJECT
  45
  46 public:
  47     enum EchoModes { OneStar, ThreeStars, NoEcho };
  48
  49     /**
  50      * Constructs a password input widget using the user's global "echo mode" setting.
  51      */
  52     explicit K3PasswordEdit(QWidget *parent=0);
  53     // KDE4: either of the two must go! add default values for parameters
  54
  55     /**
  56      * Constructs a password input widget using echoMode as "echo mode".
  57      * Note that echoMode is a QLineEdit::EchoMode.
  58      */
  59     explicit K3PasswordEdit(EchoMode echoMode, QWidget *parent = 0);
  60
  61     /**
  62      * Constructs a password input widget using echoMode as "echo mode".
  63      * Note that echoMode is a K3PasswordEdit::EchoModes.
  64      */
  65     explicit K3PasswordEdit(EchoModes echoMode, QWidget *parent = 0);
  66
  67     /**
  68      * Destructs the widget.
  69      */
  70     ~K3PasswordEdit();
  71
  72     /**
  73      * Returns the password. The memory is freed in the destructor
  74      * so you should make a copy.
  75      */
  76     const char *password() const;
  77
  78     /**
  79      * Erases the current password.
  80      */
  81     void erase();
  82
  83     static const int PassLen;
  84
  85     /**
  86      * Set the current maximum password length.  If a password longer than the limit
  87      * specified is currently entered, it is truncated accordingly.
  88      *
  89      * The length is capped to lie between 0 and 199 inclusive.
  90      *
  91      * @param newLength: The new maximum password length
  92      */
  93     void setMaxPasswordLength(int newLength);
  94
  95     /**
  96      * Returns the current maximum password length.
  97      */
  98     int maxPasswordLength() const;
  99
 100 public Q_SLOTS:
 101     /**
 102      * Reimplementation
 103      */
 104     virtual void insert( const QString &);
 105
 106 protected:
 107     virtual void keyPressEvent(QKeyEvent *);
 108     virtual void focusInEvent(QFocusEvent *e);
 109     virtual bool event(QEvent *e);
 110
 111 private:
 112     void init();
 113     void showPass();
 114
 115     char *m_Password;
 116     int m_EchoMode, m_Length;
 117 };
 118
 119
 120 /**
 121  * @short A password input dialog.
 122  *
 123  * This dialog asks the user to enter a password. The functions you're
 124  * probably interested in are the static methods, getPassword() and
 125  * getNewPassword().
 126  *
 127  * <b>Usage example</b>\n
 128  *
 129  * \code
 130  * QCString password;
 131  * int result = K3PasswordDialog::getPassword(parent, password, i18n("Prompt message"));
 132  * if (result == K3PasswordDialog::Accepted)
 133  *     use(password);
 134  * \endcode
 135  *
 136  * \image html k3passworddialog.png "KDE Password Dialog"
 137  *
 138  * <b>Security notes:</b>\n
 139  *
 140  * Keeping passwords in memory can be a potential security hole. You should
 141  * handle this situation with care.
 142  *
 143  * @li You may want to use disableCoreDump() to disable core dumps.
 144  * Core dumps are dangerous because they are an image of the process memory,
 145  * and thus include any passwords that were in memory.
 146  *
 147  * @li You should delete passwords as soon as they are not needed anymore.
 148  * The functions getPassword() and getNewPassword() return the
 149  * password as a QCString. I believe this is safer than a QString. A QString
 150  * stores its characters internally as 16-bit wide values, so conversions are
 151  * needed, both for creating the QString and by using it. The temporary
 152  * memory used for these conversion is probably not erased. This could lead
 153  * to stray  passwords in memory, even if you think you erased all of them.
 154  *
 155  * @author Geert Jansen <jansen@kde.org>
 156  * @deprecated use KPasswordDialog or KNewPasswordDialog
 157  */
 158
 159 class KDE3SUPPORT_EXPORT K3PasswordDialog
 160     : public KDialog
 161 {
 162     Q_OBJECT
 163
 164 public:
 165     /**
 166      * This enum distinguishes the two operation modes of this dialog:
 167      */
 168     enum Types {
 169         /**
 170          * The user is asked to enter a password.
 171          */
 172         Password,
 173
 174         /**
 175          * The user is asked to enter a password and to confirm it
 176          * a second time. This is usually used when the user
 177          * changes his password.
 178          */
 179         NewPassword
 180     };
 181
 182     /**
 183      * Constructs a password dialog.
 184      *
 185      * @param type: if NewPassword is given here, the dialog contains two
 186      *        input fields, so that the user must confirm his password
 187      *        and possible typos are detected immediately.
 188      * @param enableKeep: if true, a check box is shown in the dialog
 189      *        which allows the user to keep his password input for later.
 190      * @param extraBttn: allows to show additional buttons, KDialog.
 191      * @param parent Passed to lower level constructor.
 192      */
 193     K3PasswordDialog(Types type, bool enableKeep, ButtonCodes extraBttn, QWidget *parent=0);
 194
 195
 196     /**
 197      * Construct a password dialog. Essentially the same as above but allows the
 198      * icon in the password dialog to be set via @p iconName.
 199      * @param type if NewPassword is given here, the dialog contains two
 200      * input fields, so that the user must confirm his password
 201      * and possible typos are detected immediately
 202      * @param enableKeep: if true, a check box is shown in the dialog
 203      *        which allows the user to keep his password input for later.
 204      * @param extraBttn: allows to show additional buttons.
 205      * @param iconName the name of the icon to be shown in the dialog. If empty,
 206      * a default icon is used
 207      * @param parent Passed to lower level constructor.
 208      */
 209     K3PasswordDialog(Types type, bool enableKeep, ButtonCodes extraBttn, const QString& iconName,
 210                     QWidget *parent = 0);
 211
 212     /**
 213      * Destructs the password dialog.
 214      */
 215     virtual ~K3PasswordDialog();
 216
 217     /**
 218      * Sets the password prompt.
 219      */
 220     void setPrompt(const QString &prompt);
 221
 222     /**
 223      * Returns the password prompt.
 224      */
 225     QString prompt() const;
 226
 227     /**
 228      * Adds a line of information to the dialog.
 229      */
 230     void addLine(const QString &key, const QString &value);
 231
 232     /**
 233      * Allow empty passwords? - Default: false
 234      */
 235     void setAllowEmptyPasswords(bool allowed);
 236
 237     /**
 238      * Allow empty passwords?
 239      */
 240     bool allowEmptyPasswords() const;
 241
 242     /**
 243      * Minimum acceptable password length.
 244      * Default: If empty passwords are forbidden, 1;
 245      *          Otherwise, 0.
 246      *
 247      * @param minLength: The new minimum password length
 248      */
 249     void setMinimumPasswordLength(int minLength);
 250
 251     /**
 252      * Minimum acceptable password length.
 253      */
 254     int minimumPasswordLength() const;
 255
 256     /**
 257      * Maximum acceptable password length.  Limited to 199.
 258      * Default: No limit, i.e. -1
 259      *
 260      * @param maxLength: The new maximum password length.
 261      */
 262     void setMaximumPasswordLength(int maxLength);
 263
 264     /**
 265      * Maximum acceptable password length.
 266      */
 267     int maximumPasswordLength() const;
 268
 269     /**
 270      * Password length that is expected to be reasonably safe.
 271      *
 272      * Default: 8 - the standard UNIX password length
 273      *
 274      * @param reasonableLength: The new reasonable password length.
 275      */
 276     void setReasonablePasswordLength(int reasonableLength);
 277
 278     /**
 279      * Password length that is expected to be reasonably safe.
 280      */
 281     int reasonablePasswordLength() const;
 282
 283     /**
 284      * Set the password strength level below which a warning is given
 285      * Value is in the range 0 to 99. Empty passwords score 0;
 286      * non-empty passwords score up to 100, depending on their length and whether they
 287      * contain numbers, mixed case letters and punctuation.
 288      *
 289      * Default: 1 - warn if the password has no discernable strength whatsoever
 290      * @param warningLevel: The level below which a warning should be given.
 291      */
 292     void setPasswordStrengthWarningLevel(int warningLevel);
 293
 294     /**
 295      * Password strength level below which a warning is given
 296      */
 297     int passwordStrengthWarningLevel() const;
 298
 299     /**
 300      * Returns the password entered. The memory is freed in the destructor,
 301      * so you should make a copy.
 302      */
 303     const char *password() const;
 304
 305     /**
 306      * Clears the password input field. You might want to use this after the
 307      * user failed to enter the correct password.
 308      */
 309     void clearPassword();
 310
 311     /**
 312      * Returns true if the user wants to keep the password.
 313      */
 314     bool keep() const;
 315
 316     /**
 317      * Pops up the dialog, asks the user for a password, and returns it.
 318      *
 319      * @param parent The widget the dialog belongs too
 320      * @param password The password is returned in this reference parameter.
 321      * @param caption A caption for the dialog.
 322      * @param prompt A prompt for the password. This can be a few lines of
 323      * information. The text is word broken to fit nicely in the dialog.
 324      * @param keep Enable/disable a checkbox controlling password keeping.
 325      * If you pass a null pointer, or a pointer to the value false, the checkbox
 326      * is not shown. If you pass a pointer to a true value, the checkbox
 327      * is shown and the result is stored in *keep.
 328      * @return Result code: Accepted or Rejected.
 329      */
 330     static int getPassword(QWidget *parent, QByteArray &password, const QString &caption, const QString &prompt, bool *keep = 0L);
 331
 332     /**
 333      * @overload
 334      *
 335      * @deprecated Use the new version with the caption argument
 336      */
 337     static KDE_DEPRECATED int getPassword(QWidget *parent, QByteArray &password, const QString &prompt, int *keep = 0L);
 338
 339     /**
 340      * Pops up the dialog, asks the user for a password and returns it. The
 341      * user has to enter the password twice to make sure it was entered
 342      * correctly.
 343      *
 344      * @param parent The widget the dialog belongs too
 345      * @param password The password is returned in this reference parameter.
 346      * @param caption A caption for the dialog.
 347      * @param prompt A prompt for the password. This can be a few lines of
 348      * information. The text is word broken to fit nicely in the dialog.
 349      * @return Result code: Accepted or Rejected.
 350      */
 351     static int getNewPassword(QWidget *parent, QByteArray &password, const QString &caption, const QString &prompt);
 352
 353     /**
 354      * @overload
 355      *
 356      * @deprecated Use the new version with the caption argument
 357      */
 358     static KDE_DEPRECATED int getNewPassword(QWidget *parent, QByteArray &password, const QString &prompt);
 359
 360     /**
 361      * Static helper function that disables core dumps.
 362      */
 363     static void disableCoreDumps();
 364
 365         virtual void accept();
 366
 367 protected Q_SLOTS:
 368     void slotKeep(bool);
 369
 370 protected:
 371
 372     /**
 373      * Virtual function that can be overridden to provide password
 374      * checking in derived classes. It should return @p true if the
 375      * password is valid, @p false otherwise.
 376      */
 377     virtual bool checkPassword(const char *password);
 378
 379
 380 private Q_SLOTS:
 381   void enableOkBtn();
 382
 383 private:
 384     void init();
 385     void erase();
 386
 387     int m_Keep, m_Type, m_Row;
 388     QLabel *m_pHelpLbl;
 389     QGridLayout *m_pGrid;
 390     QWidget *m_pMain;
 391     K3PasswordEdit *m_pEdit, *m_pEdit2;
 392
 393 private:
 394     class K3PasswordDialogPrivate;
 395     K3PasswordDialogPrivate* const d;
 396 };
 397
 398 #endif // K3PasswordDialog_H
 399