From 74838e3fd16477dfc862eece8cec5cad20a3aabc Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Tue, 3 Apr 2007 10:59:57 +0000 Subject: [PATCH] API dox update for recent changes svn path=/trunk/kdesupport/qca/; revision=649889 --- include/QtCrypto/qca_keystore.h | 131 +++++++++++++++++++++++++++++++- 1 file changed, 128 insertions(+), 3 deletions(-) diff --git a/include/QtCrypto/qca_keystore.h b/include/QtCrypto/qca_keystore.h index ecc8f223..2134e364 100644 --- a/include/QtCrypto/qca_keystore.h +++ b/include/QtCrypto/qca_keystore.h @@ -47,6 +47,90 @@ namespace QCA Single entry in a KeyStore This is a container for any kind of object in a KeyStore + (such as PGP keys, or X.509 certificates / private keys). + + KeyStoreEntry entities are normally accessed through the KeyStore, + however it is possible to access KeyStoreEntry objects directly, + using a persistent id(). + + \code + QString entry_id = someKeyStoreEntry.id(); + [ app saves entry_id to disk ] + [ app quits ] + ... + [ app launches ] + [ app reads entry_id from disk ] + KeyStoreEntry entry(entry_id); + printf("Entry name: [%s]\n", qPrintable(entry.name())); + \endcode + + Keep in mind that retrieving a passive entry's content + (e.g. with entry.certificate()) may return a null object. + To ensure the entry is available, do: + + \code + if(entry.ensureAvailable()) + { + Certificate cert = entry.certificate(); + ... + } + \endcode + + ensureAvailable() blocks and may cause hardware access, but + if it completes successfully then you may use the entry's + content. It also means, in the case of a Smart Card token, + that it is probably inserted. + + To watch this id asynchronously, you would do: + + \code + KeyStoreEntryWatcher *watcher = new KeyStoreEntryWatcher(entry); + connect(watcher, SIGNAL(available()), SLOT(entry_available())); + ... + void entry_available() + { + // entry now available + Certificate cert = watcher->entry().certificate(); + } + \endcode + + Note that a provider can supply valid content objects even + for unavailable entries, if they have enough metadata to + provide that (qca-pkcs11 for example, puts the entire cert + in the id). + + Now, even though an entry may be available, it does not + mean you have access to use it for operations. For + example, a KeyBundle offered by a Smart Card that is + available is guaranteed to give you valid objects, however + as soon as you try to use the PrivateKey object for a + signing operation, a PIN might be asked for. You can call + ensureAccess() if you want to synchronously provide the PIN + early on: + + \code + if(entry.ensureAccess()) + { + // do private key stuff + ... + } + \endcode + + Note that you don't have to call ensureAvailable() before + ensureAccess(). Calling the latter is enough to imply + both. + + After an application is configured to use a particular key, + it is expected that its usual running procedure will be: + + - Construct KeyStoreEntry from the known id. + - If the content object is not available, wait for it + (with either ensureAvailable() or KeyStoreEntryWatcher). + - Pass the content object(s) to a high level operation like TLS. + + In this case, any PIN prompting and private key operations + would be caused/handled from the TLS object. + */ class QCA_EXPORT KeyStoreEntry : public Algorithm { @@ -94,7 +178,32 @@ namespace QCA */ bool isNull() const; + /** + Test if the key is available for use. + + A key is considered available if the KeyStore + that it is part of is present. + + \sa ensureAvailable + \sa isAccessible + */ bool isAvailable() const; + + /** + Test if the key is currently accessible. + + This means that the private key part can be used + at this time. For a smartcard, this means that all + required operations (e.g. login / PIN entry) are + completed. + + If isAccessible() is true, then the key + is necessarily available (i.e. isAvailable() is + also true). + + \sa ensureAccessible + \sa isAvailable + */ bool isAccessible() const; /** @@ -159,6 +268,7 @@ namespace QCA /** Returns true if the entry is available, otherwise false. + Available means that the retrieval functions (like keyBundle(), certificate(), pgpPublicKey(), etc) will return non-null objects. Entries retrieved from a @@ -167,6 +277,9 @@ namespace QCA on an already available entry may cause the entry to be refreshed. + \sa isAvailable + \sa ensureAccess + \note This function is blocking. */ bool ensureAvailable(); @@ -175,6 +288,9 @@ namespace QCA Like ensureAvailable, but will also ensure that the token is inserted / PIN is provided if needed. + + \sa isAccessible + \sa ensureAvailable */ bool ensureAccess(); @@ -381,16 +497,25 @@ namespace QCA Access keystores, and monitor keystores for changes. - If you are looking to use this class, you probably want to - take a reference to the global KeyStoreManager, using the - QCA::keyStoreManager() function. You then need to start() + Before you can access a KeyStore, you must create a + KeyStoreManager. You then need to start() the KeyStoreManager, and either wait for the busyFinished() signal, or block using waitForBusyFinished(). + + If you know the KeyStoreEntry that you need, you can + use KeyStore passively, as described in the KeyStoreEntry + documentation. */ class QCA_EXPORT KeyStoreManager : public QObject { Q_OBJECT public: + + /** + Create a new KeyStoreManager + + \param parent the parent for this object + */ KeyStoreManager(QObject *parent = 0); ~KeyStoreManager();