Credentials storage duration
============================
How long credentials are stored depends on a couple of factors. The first is
whether a window-id (see QWidget::WId) was provided when the password request
was made. The other is the state of KIO::AuthInfo's keepPassword flag.

If the window-id parameter is missing, the credentials are stored for the
entire duration of the current KDE session. Otherwise, they are only kept
until the application(s) associated with the window-id exit.

The "keepPassword" flag on the other hand only matters for caching credentials
in a persistent storage such as KWallet. If this flag is set to false, then
credentials are only kept in memory based on the value of window-id as discussed
above. See the documentation for the "keepPassword" property in KIO::AuthInfo
for more details.

Dawit A. <adawit@kde.org>

Sequence numbers
================
The idea is that whenever the user is queried for a password this
login/pw combination gets a seq-nr. When  a worker needs a  login/pw
it asks kpasswdserver and sends along the last seqnr it received. If
this seqnr is older (lower) than the seq nr of the login/pw
combination stored in kpasswdserver then apparently the user has
already been prompted for a new login/pw combination since the last
time this worker asked for a login/pw and therefore it is not necessary
to prompt the user again but kpassword will send the KIO worker this
new login/pw combination. If this new combination fails as well the
user is being prompted for a new login/pw combo since the one stored
in kpasswdserver doesn't work.

Let me try to draw the situation I had in mind when writing this:

Worker1		Worker2			kpasswdserver
Asks for auth
					asks user for login/pw (1)
sends login/pw (1) to ftp site
		Asks for auth
					sends back login/pw (1)
		sends login/pw (1) to ftp site
gets login error,
asks for new auth
sends along seq.nr 1
					seq.nr 1 == (1) -->
					asks user for new login/pw (2)
sends login/pw (2) to ftp site
		gets login error,
		asks for new auth
		sends along seq.nr 1
					seq.nr 1 < (2) -->
					don't ask user for new login/pw
					but send back login/pw (2) without asking
		sends login/pw (2) to ftp site


Actually, I had mostly http in mind, and not so much ftp. In http you 
typically try without password first, and only when you get an 
authentication error you ask for a password. The above scenario is 
then suddenly a lot more common than with ftp because it can happen 
that you have 4 requests /workers who all discover at about the 
same time that they need to have authentication credentials. The 
above scenario (and the seq. nrs) is to prevent that you get 4 login 
dialogs in such case.

Now the assumption in this all, looking back on it, seems to be that 
when you ask for the same auth credentials twice in a row, it must be 
that the credentials issued the first time where wrong, and you will 
be prompted again. But if the user goes to ftp-site1, then 
ftp-site2 and then back to ftp-site1 again, the credentials for ftp-site1
are still valid. This is why we reset the seq.nr stored in the KIO worker
to 0 whenever the KIO worker switches hosts (or logins).

Waldo Bastian <bastian@kde.org>
