Git commit 176decc75c86922aad91102273d24539e6e06a31 by Burkhard Lück. Committed on 11/08/2016 at 10:06. Pushed by lueck into branch 'master'.
Update KWalletmanager docbook to 16.04 remove header entities already in kdoctools bump date + releaseinfo new screenshots add info about default wallet kdewallet add encrypted import + export, remove obsolete "Save as" correct location of .kwl file remove systen tray icons, not shown by default any longer remove commented section about ksecrets remove dead link to techbase REVIEW:128378 M +- -- doc/application-request-to-open-wallet.png M +- -- doc/error-nokey.png M +- -- doc/first-open-request.png M +94 -155 doc/index.docbook M +- -- doc/key-selection.png M +- -- doc/kwallet-applications.png M +- -- doc/kwallet-edit.png M +- -- doc/kwalletmanager.png M +- -- doc/openwallet-request.png D +- -- doc/oxygen48-status-wallet-closed.png D +- -- doc/oxygen48-status-wallet-open.png M +- -- doc/save-login-information.png M +- -- doc/wallet-encryption-selection.png http://commits.kde.org/kwallet/176decc75c86922aad91102273d24539e6e06a31 diff --git a/doc/application-request-to-open-wallet.png b/doc/application-request-to-open-wallet.png index 819eb1a..97fb656 100644 Binary files a/doc/application-request-to-open-wallet.png and b/doc/application-request-to-open-wallet.png differ diff --git a/doc/error-nokey.png b/doc/error-nokey.png index 39a1e56..1420053 100644 Binary files a/doc/error-nokey.png and b/doc/error-nokey.png differ diff --git a/doc/first-open-request.png b/doc/first-open-request.png index 1940dbc..54adcba 100644 Binary files a/doc/first-open-request.png and b/doc/first-open-request.png differ diff --git a/doc/index.docbook b/doc/index.docbook index 19ea337..98a2d76 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -1,7 +1,5 @@ <?xml version="1.0" ?> <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [ - <!ENTITY kwallet5 "<application>KWallet</application>"> - <!ENTITY kwalletmanager5 "<application>KWallet Manager</application>"> <!ENTITY % addindex "IGNORE"> <!ENTITY % English "INCLUDE"> ]> @@ -27,8 +25,8 @@ <legalnotice>&FDLNotice;</legalnotice> -<date>2013-11-19</date> -<releaseinfo>2.0 (&kde; 4.12)</releaseinfo> +<date>2016-07-05</date> +<releaseinfo>Applications 16.04</releaseinfo> <abstract> <para> @@ -37,7 +35,6 @@ passwords.</para> </abstract> - <keywordset> <keyword>KDE</keyword> <keyword>Kwallet</keyword> @@ -55,7 +52,7 @@ which is sensitive. In particular, you will typically have many passwords to manage. Remembering them is difficult and writing them down on paper or in a text file is insecure.</para> -<para>&kwallet5; provides a secure way to store passwords and other secret information, +<para>&kwallet5; provides a secure way to store passwords and other secret information, allowing the user to remember only a single password instead of numerous different passwords and credentials. </para> @@ -65,19 +62,26 @@ allowing the user to remember only a single password instead of numerous differe <para>Wallet is a password storage. It is usually sufficient to have just one wallet secured by one master password but you can organize your large collection of passwords by wallets using &kwalletmanager5;.</para> -<para>There are three ways to create a new wallet:</para> +<para>By default a wallet named <guilabel>kdewallet</guilabel> will be used to store your passwords. +This wallet is secured by your login password and will automatically be opened at login, +if kwallet_pam is installed and properly configured. On certain distros (⪚ Archlinux) kwallet_pam is not installed by default</para> + + +<para>Other wallets have to be opened manually.</para> + +<para>There are two ways to create a new wallet:</para> <itemizedlist> -<listitem><para>Use the menu item <menuchoice><guimenu>File</guimenu><guimenuitem>New +<listitem><para>Use the menu item <menuchoice><guimenu>File</guimenu><guimenuitem>New Wallet</guimenuitem></menuchoice> in the &kwalletmanager5;</para></listitem> -<listitem><para>Use the <guibutton>New</guibutton> button in the &systemsettings; module +<listitem><para>Use the <guibutton>New</guibutton> button in the &systemsettings; module <guilabel>KDE Wallet</guilabel></para></listitem> - -<listitem><para>If you have not created a wallet yet, see section <link linkend="kwallet-using">Using &kwallet5;</link>. -</para></listitem> </itemizedlist> +<para>If you have not created a wallet yet, see section <link linkend="kwallet-using">Using &kwallet5;</link>. +</para> + <para>&kwallet5; offers two different ways to store your data:</para> <screenshot> @@ -128,7 +132,7 @@ before the data is deciphered and accessible by the applications. <textobject><phrase>No GPG key found</phrase></textobject> </mediaobject> </screenshot> -<para>The screenshots above show the case where an encryption capable GPG key was not +<para>The screenshots above show the case where an encryption capable GPG key was not found on the system. Please use applications like &kgpg; or &kleopatra; to create a key an try again.</para> <para>If a GPG key was found you will get the next dialog where you can select a key to use for your new wallet. @@ -141,13 +145,13 @@ found on the system. Please use applications like &kgpg; or &kleopatra; to creat </mediaobject> </screenshot> -<para>&kwallet5; will now use GPG when storing wallets and when opening them. -The passphrase dialog only shows once. Even if the wallet is closed after initial open, -subsequent opening will occur silently during the same &kde; session. +<para>&kwallet5; will now use GPG when storing wallets and when opening them. +The passphrase dialog only shows once. Even if the wallet is closed after initial open, +subsequent opening will occur silently during the same session. </para> <para> -The same &kde; session can handle simultaneously both file formats. &kwallet5; will transparently detect +The same session can handle simultaneously both file formats. &kwallet5; will transparently detect the file format and load the correct backend to handle it.</para> <para> @@ -155,23 +159,26 @@ To use your sensitive data from your classic wallet with the new backend follow <itemizedlist> <listitem><para>Create a new GPG based wallet</para></listitem> -<listitem><para>Launch &kwalletmanager5; using &krunner; (<keycombo>&Alt; <keycap>F2</keycap></keycombo>) or other application launcher (menu) and select your old wallet then choose <menuchoice><guimenu>File</guimenu> -<guimenuitem>Export as XML</guimenuitem></menuchoice> to create an &XML; file with your sensitive data. +<listitem><para>Launch &kwalletmanager5; using &krunner; (<keycombo>&Alt; <keycap>F2</keycap></keycombo>) +or other application launcher (menu) and select your old wallet. +Then choose <menuchoice><guimenu>File</guimenu> +<guimenuitem>Export as encrypted</guimenuitem></menuchoice> to create an archive file with your sensitive data. </para></listitem> <listitem><para>Select the new GPG based wallet then choose <menuchoice><guimenu>File</guimenu> -<guimenuitem>Import XML</guimenuitem></menuchoice> and select the file you just saved.</para> -<para>Encrypt the &XML; file to keep a backup.</para> +<guimenuitem>Import encrypted</guimenuitem></menuchoice> and select the file you just saved.</para> </listitem> -<listitem><para><menuchoice><guimenu>File</guimenu><guimenuitem>Import Wallet</guimenuitem></menuchoice> -but in that case you have to select the <filename class="extension">.kwl</filename> file corresponding -to your old wallet, located in <filename class="directory">$<envar>KDEHOME</envar>/.local/share/kwalletd</filename>. -</para></listitem> -<listitem><para>Go to &systemsettings; <menuchoice><guimenu>Account Details</guimenu> <guimenuitem>KDE -Wallet</guimenuitem></menuchoice> and select the newly created GPG based wallet from the <guilabel>Select + +<listitem><para>Go to &systemsettings; <menuchoice><guimenu>Account Details</guimenu> <guimenuitem>KDE +Wallet</guimenuitem></menuchoice> and select the newly created GPG based wallet from the <guilabel>Select wallet to use as default</guilabel> combobox. </para></listitem> </itemizedlist> +<para>Alternativly use <guimenuitem>Import a wallet</guimenuitem> +but in that case you have to select the <filename class="extension">.kwl</filename> file corresponding +to your old wallet, located in the folder <filename class="directory">kwalletd</filename> +in <userinput>qtpaths --paths GenericDataLocation</userinput>. +</para> </listitem> </varlistentry> @@ -182,19 +189,19 @@ wallet to use as default</guilabel> combobox. for the most secure operation, you should use one wallet for local passwords, and another for network passwords and form data. You can configure this behavior in the &kwallet5; &systemsettings; module, however -the default setting is to store everything in one wallet.</para> +the default setting is to store everything in one wallet named <guilabel>kdewallet</guilabel>.</para> </tip> <para>A wallet is by default closed, which means that you must supply a password to open it. Once the wallet is opened, the contents can -be accessed.</para> +be read by any user process, so this may be a security issue.</para> </sect1> <sect1 id="kwallet-using"> <title>Using &kwallet5;</title> -<para>If you visit ⪚ the &kde; bugtracker and enter the login data for -the first time, a dialog pops up offering to store the password in an +<para>If you visit ⪚ the &kde; bugtracker and enter the login data for +the first time, a dialog pops up offering to store the password in an encrypted wallet:</para> <screenshot> @@ -205,13 +212,24 @@ encrypted wallet:</para> </mediaobject> </screenshot> -<para>If you want to store this information, select <guibutton>Store</guibutton> -to proceed. In case you did not create a wallet so far, the next dialog asks for +<para>If you want to store this information, select <guibutton>Store</guibutton> +to proceed. In case you did not create a wallet so far, the next dialog asks for the encryption backend and creates a wallet named kdewallet. </para> -<para>Next time you visit the same website again, the application requests to open the wallet. -Enter the wallet password and click the <guibutton>Open</guibutton> button.</para> +<para>Next time you visit the same website again, the application retrieves the login data +from an open wallet and prefills the forms with these secrets.</para> + +<screenshot> +<screeninfo>Prefilled login information</screeninfo> +<mediaobject> +<imageobject><imagedata fileref="prefilled-forms.png" format="PNG"/></imageobject> +<textobject><phrase>Prefilled login information</phrase></textobject> +</mediaobject> +</screenshot> + +<para>If the wallet is closed the application requests to open the wallet. +Enter the wallet password and click the <guibutton>Open</guibutton> button.</para> <screenshot> <screeninfo>Request to open a wallet</screeninfo> @@ -222,7 +240,7 @@ Enter the wallet password and click the <guibutton>Open</guibutton> button.</par </screenshot> <para>This connects the application to the wallet, enables it to read the login data from the wallet -and to restore the login information for this website. Once an application is connected to +and to restore the login information for this website. Once an application is connected to the wallet, it can automatically restore any login information stored in the wallet.</para> </sect1> @@ -243,29 +261,11 @@ deleting wallets and manipulating their contents (changing keys, ...).</para> <para>The &kwalletmanager5; application is launched with <menuchoice> <guimenu>Applications</guimenu><guisubmenu>System</guisubmenu> <guimenuitem>Wallet Management Tool</guimenuitem></menuchoice> from the -application launcher. +application launcher. Alternatively start &krunner; with shortcut <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> and enter <command>kwalletmanager5</command>.</para> -<para>A system tray icon indicates that a wallet is open: - <mediaobject> - <imageobject> - <imagedata fileref="oxygen48-status-wallet-open.png"/> - </imageobject> - </mediaobject> - -When all -wallets are closed, the icon will reflect this by showing a closed -wallet: -<mediaobject> - <imageobject> - <imagedata fileref="oxygen48-status-wallet-closed.png"/> - </imageobject> - </mediaobject> - -</para> - <para>Click once on the system tray wallet icon to display the &kwalletmanager5; window.</para> <para> @@ -273,7 +273,7 @@ window.</para> <screeninfo>Main window with one wallet</screeninfo> <mediaobject> <imageobject> -<imagedata fileref="kwalletmanager5.png"/> +<imagedata fileref="kwalletmanager.png"/> </imageobject> <textobject> <phrase>Main window with one wallet</phrase> @@ -283,7 +283,7 @@ window.</para> </screenshot> </para> -<!--FIXME +<!--FIXME How to get assistant "First Use"? kwalletwizardpageintro.ui Last code change with http://websvn.kde.org/?view=revision&revision=882694 see also https://bugs.kde.org/show_bug.cgi?id=290309 @@ -291,10 +291,9 @@ see also https://bugs.kde.org/show_bug.cgi?id=290309 <sect1 id="kwalletmanager-wallet-window"> <title>The Wallet Window</title> -<para>If you have more than one wallet all available wallets are shown as icons on the left. The Icons reflect the -current wallet status, either open or closed. -</para> -<para>Clicking on a wallet in the &kwalletmanager5; window will display +<para>If you have more than one wallet all available wallets are shown on the left.</para> + +<para>Clicking on a wallet in the &kwalletmanager5; window will display that wallet's status and the contents of an opened wallet. A wallet may contain any number of folders, which allow storing of password information. By default a wallet will contain folders named Form Data and Passwords. @@ -312,7 +311,7 @@ will contain folders named Form Data and Passwords. <caption><para>Main window with two wallets</para></caption> </mediaobject> </screenshot> -<para>Use <guibutton>Open</guibutton> to display the content of a closed wallet. +<para>Use <guibutton>Open</guibutton> to display the content of a closed wallet. You will be requested to enter the master password.</para> <sect2> @@ -323,11 +322,11 @@ You will be requested to enter the master password.</para> <itemizedlist> <listitem><para>A search line to filter the items of the current wallet</para></listitem> -<listitem><para>The tree view of the folders contained in the wallet. -Click the <guiicon>></guiicon> / <guiicon>v</guiicon> icons to expand or collapse +<listitem><para>The tree view of the folders contained in the wallet. +Click the <guiicon>></guiicon> / <guiicon>v</guiicon> icons to expand or collapse the tree view.</para></listitem> -<listitem><para>The contents of the selected folder entry at the right side. -By default the password and value are hidden. To display and edit them enable +<listitem><para>The contents of the selected folder entry at the right side. +By default the password and value are hidden. To display and edit them enable <guilabel>Show values</guilabel> or click the <guilabel>Show Contents</guilabel> button. </para></listitem> </itemizedlist> @@ -349,23 +348,24 @@ locations.</para> <sect3 id="kwallet-import-export"> <title>Import and Export</title> -<para>If you want to transfer your secrets to another device or computer use -the actions in the <guimenu>File</guimenu> menu. With <guimenuitem>Save As</guimenuitem> -wallets can be exported into an encrypted <filename class="extension">.kwl</filename> file. -Importing the <filename class="extension">.kwl</filename> file you have to provide the master password of the wallet. +<para>If you want to transfer your secrets to another device or computer use +the actions in the <guimenu>File</guimenu> menu. With <guimenuitem>Export as encrypted</guimenuitem> +wallets can be exported into an encrypted archive file. +Importing this archive file with <guimenuitem>import encrypted</guimenuitem> +you have to provide the master password of the wallet. </para> -<para>Alternatively a <filename class="extension">.xml</filename> file can be used for transferring +<para>Alternatively a <filename class="extension">.xml</filename> file can be used for transferring a wallet. Keep in mind that all secrets are stored as plain text in this file. </para> </sect3> <sect3 id="kwallet-adding-entries"> <title>Adding Entries Manually</title> -<para>Open the context menu with the &RMB; click on <guilabel>Maps</guilabel> or +<para>Open the context menu with the &RMB; click on <guilabel>Maps</guilabel> or <guilabel>Passwords</guilabel> in the <guilabel>Folder</guilabel> tree view. -Select <guimenuitem>New</guimenuitem> and choose a name for the new entry.</para> -<para>In the folder contents pane select <guilabel>New Entry</guilabel> from -the context menu of <quote>Form Data</quote> or <quote>Passwords</quote>. +Select <guimenuitem>New</guimenuitem> or <guimenuitem>New Folder</guimenuitem> and choose a name for the new entry.</para> +<para>In the folder contents pane select <guilabel>New Folder</guilabel> from +the context menu of <quote>Form Data</quote> or <quote>Passwords</quote>. For passwords click the <guilabel>Show Contents</guilabel> button, enter the new password. For Maps you have to add a <guilabel>Key</guilabel> and a <guilabel>Value</guilabel>. Click the <guilabel>Save</guilabel> button to store the new entries in the encrypted @@ -390,7 +390,7 @@ wallet file. </mediaobject> </screenshot> </para> -<para>The first list shows all applications currently connected to the selected wallet. +<para>The first list shows all applications currently connected to the selected wallet. Use the button at the right side of each entry to disconnect the application.</para> <para>In the second list all applications are displayed which are authorized to access the wallet. @@ -452,7 +452,11 @@ again.</para> <varlistentry> <term><guilabel>Select wallet to use as default:</guilabel></term> <listitem> -<para>Select which wallet you want to use as default wallet.</para> +<para>Select which wallet you want to use as default wallet. +Please keep in mind that only the wallet named <guilabel>kdewallet</guilabel> +will be opened automatically at login, if this wallet and your login +password are identical. +</para> </listitem> </varlistentry> @@ -504,6 +508,18 @@ Manager</guibutton>, which does precisely that.</para> <para>Next there is a tree style view of the access controls for your wallets.</para> +<screenshot> +<screeninfo>Access Control</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kwallet-access-control.png"/> +</imageobject> +<textobject> +<phrase>Access Control</phrase> +</textobject> +</mediaobject> +</screenshot> + <para>Click with the &LMB; on the <guiicon>></guiicon> symbol beside a wallet name to expand the tree. You will see the name of each application that has asked for access to the wallet, and the policy you set for it. You cannot edit @@ -515,7 +531,7 @@ context menu that appears, or by simply selecting it and pressing the <para>An application that has been allowed access to a wallet is granted access to all passwords stored inside.</para> -<para>If you erroneously configured an application not to use the &kde; &kwalletmanager5; +<para>If you erroneously configured an application not to use the &kwallet5; delete the policy for this application here.</para> <!-- FIXME difference to Revoke Authorization in kwallermanager?--> <para> @@ -535,70 +551,7 @@ On the next start of this application you can define a new policy for access to </screenshot> </sect1> -<!-- ksecrets moved to playground in 4.9 -<sect1 id="ksecretsync-kcontrol-module"> -<title>&kde; Secret Sync</title> - -<para>KDE Secret Sync tool aims to help synchronize secrets, such as passwords -and login-in account information, between several devices running KDE. -It comes as a feature of the new KSecretsService infrastructure. For -more information about this infrastructure, please check the -<ulink url="http://techbase.kde.org/Projects/Utils/ksecretsservice";>KSecretsService page</ulink> -and also the -<ulink url="https://projects.kde.org/projects/kde/kdeutils/ksecrets";>project information page</ulink>. This tool is -currently under development.</para> - -<para>&kde; Secret Sync uses cryptography to securely exchange the secrets -between the devices. As such, it can be used over insecure connections, -such as the Internet.</para> ---> -<!-- not in gui 4.8.0 -<para>The operation is quite simple and it can follow one of the two scenarios:</para> -<itemizedlist> -<listitem><para>synchronize using a centralized resource</para></listitem> -<listitem><para>peer-to-peer synchronization</para></listitem> -</itemizedlist> -<sect2 id="centralized-resource"> -<title>Using a centralized resource</title> -<para>This operating mode requires full access to an IMAP server. The &kde; -Secret Sync tool creates an encrypted resource under the folder of your -choice then it updates it each time a local secret collection changes, -as notified by the KSecretsService infrastructure. This occurs each time -an application updates it's secret information. &kde; Secret Sync tool -periodically checks this central resource for modifications and when -updates are found, then they are pushed to the corresponding local -collection.</para> - -<para>This case requires permanent connection to an IMAP server. The &kde; -Secret Sync tool will hold sync operations during network outages. The -security level of this kind of operation depends of the security of the -IMAP server and the encrypting algorithm used to created the centralized -resource. On the other hand, storing the secrets on that centralized -resources can also be viewed as a backup.</para> -</sect2> ---> -<!-- -<sect2 id="peer-to-peer-synchronization"> -<title>Peer-to-peer synchronization</title> -<para>This operation mode does not require access to a centralized (IMAP) -server. A list of known computers is used instead. &kde; Secret Sync will -initiate secret exchange sessions with each of it's known computers over -a SSH tunnel. The local secret changes are propagated to the other known -computers as soon as they are detected.</para> - -<para>This case require a network connection between known devices. The &kde; -Secret Sync tool will hold sync operations with the devices that are not -available due to network outages. A naming service should be used for -devices that change IP address with each connection.</para> - -<para>On the <guilabel>General</guilabel> tab check <guilabel>Enable auto synchronization</guilabel> -and adjust the port your computer is listening for this service. Go to the -<guilabel>Computers</guilabel> tab and add all remote computer names and the -port numbers they are listening for synchronization of secrets.</para> -</sect2> -</sect1> ---> </chapter> <chapter id="advanced-features"> @@ -612,20 +565,6 @@ copy, move, or link the wallet, as desired.</para> USB keychain, so that you can take your passwords with you to work or on a vacation, and still have easy access to important sites.</para> -<para>Future versions will have built-in functions for easy export or -copying of data to portable devices.</para> - - <note> - <para> - Information on the internal structure of &kwallet5; and some useful links - to the code where you can find the answers on questions about the - structure of the passwords records and the ciphers applied to keep - passwords confident can be found on - <ulink url="http://techbase.kde.org/Projects/Utils/kwallet";>&kwallet5; - TechBase page</ulink>. - </para> - </note> - </chapter> <chapter id="credits-and-license"> diff --git a/doc/key-selection.png b/doc/key-selection.png index 8cfa1ee..697ee9e 100644 Binary files a/doc/key-selection.png and b/doc/key-selection.png differ diff --git a/doc/kwallet-applications.png b/doc/kwallet-applications.png index 1ddf61d..3b08080 100644 Binary files a/doc/kwallet-applications.png and b/doc/kwallet-applications.png differ diff --git a/doc/kwallet-edit.png b/doc/kwallet-edit.png index 3cd865f..245e639 100644 Binary files a/doc/kwallet-edit.png and b/doc/kwallet-edit.png differ diff --git a/doc/kwalletmanager.png b/doc/kwalletmanager.png index f7f2714..df1544c 100644 Binary files a/doc/kwalletmanager.png and b/doc/kwalletmanager.png differ diff --git a/doc/openwallet-request.png b/doc/openwallet-request.png index 7d4c62c..27fde4e 100644 Binary files a/doc/openwallet-request.png and b/doc/openwallet-request.png differ diff --git a/doc/oxygen48-status-wallet-closed.png b/doc/oxygen48-status-wallet-closed.png deleted file mode 100644 index 842c8d9..0000000 Binary files a/doc/oxygen48-status-wallet-closed.png and /dev/null differ diff --git a/doc/oxygen48-status-wallet-open.png b/doc/oxygen48-status-wallet-open.png deleted file mode 100644 index 0865fec..0000000 Binary files a/doc/oxygen48-status-wallet-open.png and /dev/null differ diff --git a/doc/save-login-information.png b/doc/save-login-information.png index 5948bc9..eb3d55c 100644 Binary files a/doc/save-login-information.png and b/doc/save-login-information.png differ diff --git a/doc/wallet-encryption-selection.png b/doc/wallet-encryption-selection.png index 040d417..0f2c314 100644 Binary files a/doc/wallet-encryption-selection.png and b/doc/wallet-encryption-selection.png differ
