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