Commit cad54768 authored by Ingo Klöcker's avatar Ingo Klöcker
Browse files

Update documentation

GnuPG-bug-id: 5283
parent 011e2819
......@@ -33,61 +33,46 @@ class Key;
namespace Kleo
{
/**
* Class to find Keys for E-Mail encryption.
* Class to find Keys for E-Mail signing and encryption.
*
* The KeyResolver uses the Keycache to find keys for signing
* or encryption.
*
* Overrides can be provided for address book integration if the
* format is not Auto overrides will only be respected if they
* match the format provided in the constructor.
* Overrides can be provided for address book integration.
*
* If no override key is provided for an address the key
* If no override key(s) are provided for an address and no
* KeyGroup for this address is found, then the key
* with a uid that matches the address and has the highest
* validity is used. If both keys have the same validity
* the newest subkey is used.
* validity is used. If both keys have the same validity,
* then the key with the newest subkey is used.
*
* The KeyResolver also supports groups so the number of
* encryption keys does not necessarily
* need to match the amount of sender addresses. For this reason
* maps are used heavily to map:
* maps are used to map addresses to lists of keys.
*
* CryptoFormat
* - Addresses
* -- For each Address a List of Keys
*
* As a caller you should iterate over the CryptoFormats and
* send one message for each format for the recipients and signed
* The keys can be OpenPGP keys and S/MIME (CMS) keys.
* As a caller you need to partition the keys by their protocol and
* send one message for each protocol for the recipients and signed
* by the signing keys.
*
* If the CryptoMessageFormat is Auto the minimum number
* of CryptoMessageFormats is returned that respects all overrides.
*
* -----
* Planned:
*
* As the central place to manage mail encryption / signing keys
* the Keyresolver will also show various warning / nagging messages
* and offer solutions if nagging is not explicitly turned off.
* These include:
*
* - If own keys or subkeys are about to expire:
* Offer to extend their expiration date.
*
* - (S/MIME) If they are about to expire: Offer
* to generate a new CSR.
*
* - If a user has not marked a key as backed up and
* uses it for encryption for several mails.
*
* - If a user has multiple keys for a sender address and they
* are not cross signed. Offer to cross sign / publish.
*/
class KLEO_EXPORT KeyResolver : public QObject
{
Q_OBJECT
public:
/**
* Solution represents the solution found by the KeyResolver.
* @a protocol hints at the protocol of the signing and encryption keys,
* i.e. if @a protocol is either @c GpgME::OpenPGP or @c GpgME::CMS, then
* all keys have the corresponding protocol. Otherwise, the keys have
* mixed protocols.
* @a signingKeys contains the signing keys to use. It contains
* zero or one OpenPGP key and zero or one S/MIME key.
* @a encryptionKeys contains the encryption keys to use for the
* different recipients. The keys of the map represent the normalized
* email addresses of the recipients.
*/
struct Solution
{
GpgME::Protocol protocol = GpgME::UnknownProtocol;
......@@ -99,27 +84,27 @@ public:
*
* @param encrypt: Should encryption keys be selected.
* @param sign: Should signing keys be selected.
* @param format: A specific key protocol (OpenPGP, S/MIME) for selection. Default: Both protocols.
* @param protocol: A specific key protocol (OpenPGP, S/MIME) for selection. Default: Both protocols.
* @param allowMixed: Specify if multiple message formats may be resolved.
**/
explicit KeyResolver(bool encrypt, bool sign,
GpgME::Protocol format = GpgME::UnknownProtocol,
GpgME::Protocol protocol = GpgME::UnknownProtocol,
bool allowMixed = true);
~KeyResolver() override;
/**
* Set the list of recipient addresses. Also looks
* up possible keys, but doesn't interact with the user.
* Set the list of recipient addresses.
*
* @param addresses: A list of unnormalized addresses
* @param addresses: A list of (not necessarily normalized) email addresses
*/
void setRecipients(const QStringList &addresses);
/**
* Set the senders address.
* Set the sender's address.
*
* Sender address will be added to encryption keys and used
* for signing key resolution if the signing keys are not
* This address is added to the list of recipients (for encryption to self)
* and it is used for signing key resolution, if the signing keys are not
* explicitly set through setSigningKeys.
*
* @param sender: The sender of this message.
......@@ -127,18 +112,22 @@ public:
void setSender(const QString &sender);
/**
* Set up possible override keys for recipients / sender
* addresses. The keys for the fingerprints are looked
* up and used when found. Does not interact with the user.
* Set up possible override keys for recipients addresses.
* The keys for the fingerprints are looked
* up and used when found.
*
* Overrides for @c GpgME::UnknownProtocol are used regardless of the
* protocol. Overrides for a specific protocol are only used for this
* protocol. Overrides for @c GpgME::UnknownProtocol takes precendent over
* overrides for a specific protocol.
*
* @param overrides: A map of \<protocol\> -> (\<address\> \<fingerprints\>)
*/
void setOverrideKeys(const QMap<GpgME::Protocol, QMap<QString, QStringList> > &overrides);
/**
* Set explicit signing keys. If this was set for a
* protocol the sender address will be only used as an additional encryption
* recipient for that protocol. */
* Set explicit signing keys to use.
*/
void setSigningKeys(const QStringList &fingerprints);
/**
......@@ -197,5 +186,3 @@ private:
std::unique_ptr<Private> d;
};
} // namespace Kleo
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment