Source: kpassdlg.h

// vi: ts=8 sts=4 sw=4 
/* This file is part of the KDE libraries
   Copyright (C) 1998 Pietro Iglio <iglio@fub.it>
   Copyright (C) 1999,2000 Geert Jansen <jansen@kde.org>

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License version 2 as published by the Free Software Foundation.

   This library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Library General Public License for more details.

   You should have received a copy of the GNU Library General Public License
   along with this library; see the file COPYING.LIB.  If not, write to
   the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
   Boston, MA 02111-1307, USA.
*/
#ifndef __KPassDlg_h_included__
#define __KPassDlg_h_included__

#include <qstring.h>
#include <qlineedit.h>
#include <qevent.h>

#include <kdialogbase.h>

class QLabel;
class QGridLayout;
class QWidget;

/**
 * @short A safe password input widget.
 * @author Geert Jansen <geertj@kde.org>
 *
 * The widget uses the user's global "echo mode" setting.
 */

class KPasswordEdit
    : public QLineEdit
{
    Q_OBJECT

public:
    /**
     * Create a widget using the user's global "echo mode" setting.
     */
    KPasswordEdit(QWidget *parent=0, const char *name=0);

    /**
     * Create a widget using echoMode as "echo mode".
     */
    KPasswordEdit(QWidget *parent, const char *name, int echoMode);
     
    ~KPasswordEdit();

    /** 
     * Returns the password. The memory is freed in the destructor
     * so you should make a copy.
     */
    const char *password() { return m_Password; }

    /** Erase the current password. */
    void erase();

    static const int PassLen = 100;
    enum EchoModes { OneStar, ThreeStars, NoEcho };

protected:
    virtual void keyPressEvent(QKeyEvent *);

private:
    void showPass();

    char *m_Password;
    int m_EchoMode, m_Length;
};


/**
 * This dialog asks the user to enter a password. The functions you're 
 * probably interested in are the static methods, @ref #getPassword() and
 * @ref #getNewPassword().
 *
 * @sect Usage example
 *
 * <pre>
 * QCString password;
 * int result = KPasswordDialog::getPassword(password, i18n("Password"));
 * if (result == KPasswordDialog::Accepted)
 *     use(password);
 * </pre>
 *
 * @sect Security notes
 *
 * Keeping passwords in memory can be a potential security hole. You should
 * handle this situation with care.
 *
 * @li You may want to use @ref #disableCoreDump() to disable core dumps. 
 * Core dumps are dangerous because they are an image of the process memory, 
 * and thus include any passwords that were in memory.
 *
 * @li You should delete passwords as soon as they are not needed anymore.
 * The functions @ref #getPassword() and @ref #getNewPassword() return the 
 * password as a QCString. I believe this is safer than a QString. A QString 
 * stores its characters internally as 16-bit wide values, so conversions are 
 * needed, both for creating the QString and by using it. The temporary 
 * memory used for these conversion is probably not erased. This could lead 
 * to stray  passwords in memory, even if you think you erased all of them.
 *
 * @short A password input dialog.
 * @author Geert Jansen <jansen@kde.org>
 */

class KPasswordDialog
    : public KDialogBase
{
    Q_OBJECT

public: 
    KPasswordDialog(int type, QString prompt, bool enableKeep=false, 
	    int extraBttn=0);
    virtual ~KPasswordDialog();

    /** Set the password prompt. */
    void setPrompt(QString prompt);

    /** Add a line of information to the dialog. */
    void addLine(QString key, QString value);

    /** 
     * Returns the password entered. The memory is freed in the destructor,
     * so you should make a copy.
     */
    const char *password() const { return m_pEdit->password(); }

    /** Returns true if the user wants to keep the password. */
    bool keep() const { return m_Keep; }

    /**
     * Pops up the dialog, asks the user for a password, and returns it.
     *
     * @param password The password is returned in this reference parameter.
     * @param prompt A prompt for the password. This can be a few lines of
     * information. The text is word broken to fit nicely in the dialog.
     * @param keep Enable/disable a checkbox controlling password keeping.
     * If you pass a null pointer, or a pointer to the value 0, the checkbox 
     * is not shown. If you pass a pointer to a nonzero value, the checkbox 
     * is shown and the result is stored in *keep.
     * @return Result code: Accepted or Rejected.
     */
    static int getPassword(QCString &password, QString prompt, int *keep=0L);

    /** 
     * Pops up the dialog, asks the user for a password and returns it. The
     * user has to enter the password twice to make sure it was entered
     * correctly.
     *
     * @param password The password is returned in this reference parameter.
     * @param prompt A prompt for the password. This can be a few lines of
     * information. The text is word broken to fit nicely in the dialog.
     * @return Result code: Accepted or Rejected.
     */
    static int getNewPassword(QCString &password, QString prompt);

    /** Static helper funtion that disables core dumps. */
    static void disableCoreDumps();

    enum Types { Password, NewPassword };

protected slots:
    void slotOk();
    void slotCancel();
    void slotKeep(bool);

protected:

    /** Virtual function that can be overridden to provide password
     * checking in derived classes. It should return @p true if the
     * password is valid, @p false otherwise. */
    virtual bool checkPassword(const char *) { return true; }

private:
    void erase();

    int m_Keep, m_Type, m_Row;
    QLabel *m_pHelpLbl;
    QGridLayout *m_pGrid;
    QWidget *m_pMain;
    KPasswordEdit *m_pEdit, *m_pEdit2;

    class KPasswordDialogPrivate;
    KPasswordDialogPrivate *d;
};


#endif // __KPassDlg_h_included__