kmail Library API Documentation

Kleo::KeyResolver Class Reference

A class to resolve signing/encryption keys w.r.t. More...

#include <keyresolver.h>

List of all members.

Public Member Functions

 KeyResolver (bool encToSelf, bool showApproval, bool oppEncryption, unsigned int format, int encrKeyNearExpiryThresholdDays, int signKeyNearExpiryThresholdDays, int encrRootCertNearExpiryThresholdDays, int signRootCertNearExpiryThresholdDays, int encrChainCertNearExpiryThresholdDays, int signChainCertNearExpiryThresholdDays)
Kpgp::Result setEncryptToSelfKeys (const QStringList &fingerprints)
Kpgp::Result setSigningKeys (const QStringList &fingerprints)
void setPrimaryRecipients (const QStringList &addresses)
void setSecondaryRecipients (const QStringList &addresses)
Action checkSigningPreferences (bool signingRequested) const
Action checkEncryptionPreferences (bool encryptionRequested) const
Kpgp::Result resolveAllKeys (bool &signingRequested, bool &encryptionRequested)
std::vector< GpgME::Key > signingKeys (CryptoMessageFormat f) const
std::vector< SplitInfo > encryptionItems (CryptoMessageFormat f) const

Friends

class EncryptionPreferenceCounter
class SigningPreferenceCounter


Detailed Description

A class to resolve signing/encryption keys w.r.t.

per-recipient preferences

Step 1: Set the information needed

The constructor takes some basic options as arguments, such as whether or not encryption was actually requested. Recipient and sender information is then set by using setEncryptToSelfKeys(), setSigningKeys(), setPrimaryRecipients() (To/Cc) and setSecondaryRecipients() (Bcc).

Step 2: Lookup and check per-recipient crypto preferences / Opportunistic Encryption

First, checkSigningPreferences() goes through all recipient's signing perferences, to determine whether or not to sign. It also takes into account the available signing keys and whether or not the user explicitly requested signing.

checkEncryptionPreferences() does the same for encryption preferences. If opportunistic encryption is enabled, recipients without encryption preferences set are treated as if they had a preference of AskWheneverPossible.

In both cases an Action code is returned, with the following meanings:

Conflict
A conflict was detected. E.g. one recipient's preference was set to "always encrypt", while another one's preference was set to "never encrypt". You should ask the user what to do.

DoIt, DontDoIt
Do/Don't sign/encrypt

Ask
(Some) crypto preferences request to prompt the user, so do it.

Impossible
Signing or encryption is impossible, e.g. due to missing keys or unsupported formats.

Step 3: Resolve all keys.

In case signing or encryption was implicitly or explicitly requested by the user, resolveAllKeys() tries to find signing keys for each required format, as well as encryption keys for all recipients (incl. the sender, if encrypt-to-self is set).

Step 4: Get signing keys.

If, after key resolving, signing is still requested and apparently possible, you can get the result of all this by iterating over the available message formats and retrieving the set of signing keys to use with a call to signingKeys().

Step 5: Get encrytion key sets.

If after key resolving, encryption is still requested and apparently possible, you can get the result of all this by calling encryptionItems() with the current message format at hand as its argument.

This will return a list of recipient-list/key-list pairs that each describe a copy of the (possibly signed) message to be encrypted independantly.

Note that it's only necessary to sign the message once for each message format, although it might be necessary to create more than one message when encrypting. This is because encryption allows the recipients to learn about the other recipients the message was encrypted to, so each secondary (BCC) recipient need a copy of it's own to hide the other secondary recipients.

Definition at line 127 of file keyresolver.h.


Member Function Documentation

Kpgp::Result Kleo::KeyResolver::setEncryptToSelfKeys const QStringList fingerprints  ) 
 

Set the fingerprints of keys to be used for encrypting to self.

Also looks them up and complains if they're not usable or found.

Kpgp::Result Kleo::KeyResolver::setSigningKeys const QStringList fingerprints  ) 
 

Set the fingerprints of keys to be used for signing.

Also looks them up and complains if they're not usable or found.

void Kleo::KeyResolver::setPrimaryRecipients const QStringList addresses  ) 
 

Set the list of primary (To/CC) recipient addresses.

Also looks up possible keys, but doesn't interact with the user.

void Kleo::KeyResolver::setSecondaryRecipients const QStringList addresses  ) 
 

Set the list of secondary (BCC) recipient addresses.

Also looks up possible keys, but doesn't interact with the user.

Action Kleo::KeyResolver::checkSigningPreferences bool  signingRequested  )  const
 

Determine whether to sign or not, depending on the per-recipient signing preferences, as well as the availability of usable signing keys.

Action Kleo::KeyResolver::checkEncryptionPreferences bool  encryptionRequested  )  const
 

Determine whether to encrypt or not, depending on the per-recipient encryption preferences, as well as the availability of usable encryption keys.

Kpgp::Result Kleo::KeyResolver::resolveAllKeys bool &  signingRequested,
bool &  encryptionRequested
 

Queries the user for missing keys and displays a key approval dialog if needed.

std::vector<GpgME::Key> Kleo::KeyResolver::signingKeys CryptoMessageFormat  f  )  const
 

Returns:
the signing keys to use (if any) for the given message format.

std::vector<SplitInfo> Kleo::KeyResolver::encryptionItems CryptoMessageFormat  f  )  const
 

Returns:
the found distinct sets of items for format f. The returned vector will contain more than one item only if secondary recipients have been specified.


The documentation for this class was generated from the following file:
KDE Logo
This file is part of the documentation for kmail Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Jul 25 11:20:34 2007 by doxygen 1.4.2 written by Dimitri van Heesch, © 1997-2003