2
* qca_keystore.h - Qt Cryptographic Architecture
3
* Copyright (C) 2003-2007 Justin Karneges <justin@affinix.com>
4
* Copyright (C) 2004,2005 Brad Hards <bradh@frogmouth.net>
6
* This library is free software; you can redistribute it and/or
7
* modify it under the terms of the GNU Lesser General Public
8
* License as published by the Free Software Foundation; either
9
* version 2.1 of the License, or (at your option) any later version.
11
* This library is distributed in the hope that it will be useful,
12
* but WITHOUT ANY WARRANTY; without even the implied warranty of
13
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14
* Lesser General Public License for more details.
16
* You should have received a copy of the GNU Lesser General Public
17
* License along with this library; if not, write to the Free Software
18
* Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA
25
Header file for classes that provide and manage keys
27
\note You should not use this header directly from an
28
application. You should just use <tt> \#include \<QtCrypto>
32
#ifndef QCA_KEYSTORE_H
33
#define QCA_KEYSTORE_H
40
class KeyStoreTracker;
41
class KeyStoreManagerPrivate;
42
class KeyStorePrivate;
45
\class KeyStoreEntry qca_keystore.h QtCrypto
47
Single entry in a KeyStore
49
This is a container for any kind of object in a KeyStore
50
(such as PGP keys, or X.509 certificates / private keys).
52
KeyStoreEntry objects are obtained through KeyStore or loaded from a
53
serialized string format. The latter method requires a KeyStoreEntry
54
obtained through KeyStore to be serialized for future loading. For
58
QString str = someKeyStoreEntry.toString();
59
[ app saves str to disk ]
63
[ app reads str from disk ]
64
KeyStoreEntry entry(str);
65
printf("Entry name: [%s]\n", qPrintable(entry.name()));
68
KeyStoreEntry objects may or may not be available. An entry is
69
unavailable if it has a private content that is not present. The
70
private content might exist on external hardware. To determine if an
71
entry is available, call isAvailable(). To ensure an entry is available
72
before performing a private key operation, call ensureAvailable. For
76
if(entry.ensureAvailable())
78
entry.keyBundle().privateKey().signMessage(...);
83
ensureAvailable() blocks and may cause hardware access, but
84
if it completes successfully then you may use the entry's private
85
content. It also means, in the case of a Smart Card token, that
86
it is probably inserted.
88
To watch this entry asynchronously, you would do:
91
KeyStoreEntryWatcher *watcher = new KeyStoreEntryWatcher(entry);
92
connect(watcher, SIGNAL(available()), SLOT(entry_available()));
94
void entry_available()
96
// entry now available
97
watcher->entry().keyBundle().privateKey().signMessage(...);
101
Unlike private content, public content is always usable even if the
102
entry is not available. Serialized entry data contains all of the
103
metadata necessary to reconstruct the public content.
105
Now, even though an entry may be available, it does not
106
mean you have access to use it for operations. For
107
example, even though a KeyBundle entry offered by a Smart Card
108
may be available, as soon as you try to use the PrivateKey object
109
for a signing operation, a PIN might be asked for. You can call
110
ensureAccess() if you want to synchronously provide the PIN
114
if(entry.ensureAccess())
116
// do private key stuff
121
Note that you don't have to call ensureAvailable() before
122
ensureAccess(). Calling the latter is enough to imply
125
After an application is configured to use a particular key,
126
it is expected that its usual running procedure will be:
128
1) Construct KeyStoreEntry from the serialized data.
129
2) If the content object is not available, wait for it
130
(with either ensureAvailable() or KeyStoreEntryWatcher).
131
3) Pass the content object(s) to a high level operation like TLS.
133
In this case, any PIN prompting and private key operations
134
would be caused/handled from the TLS object. Omit step 2 and
135
the private key operations might cause token prompting.
139
class QCA_EXPORT KeyStoreEntry : public Algorithm
143
The type of entry in the KeyStore
155
Create an empty KeyStoreEntry
160
Create a passive KeyStoreEntry based on a serialized
163
\param serialized the string containing the keystore entry information
167
KeyStoreEntry(const QString &serialized);
170
Standard copy constructor
172
\param from the source entry
174
KeyStoreEntry(const KeyStoreEntry &from);
179
Standard assignment operator
181
\param from the source entry
183
KeyStoreEntry & operator=(const KeyStoreEntry &from);
186
Test if this key is empty (null)
191
Test if the key is available for use.
193
A key is considered available if the key's private
199
bool isAvailable() const;
202
Test if the key is currently accessible.
204
This means that the private key part can be used
205
at this time. For a smartcard, this means that all
206
required operations (e.g. login / PIN entry) are
209
If isAccessible() is true, then the key
210
is necessarily available (i.e. isAvailable() is
216
bool isAccessible() const;
219
Determine the type of key stored in this object
224
The name associated with the key stored in this object
226
QString name() const;
229
The ID associated with the key stored in this object.
234
The name of the KeyStore for this key object
236
QString storeName() const;
239
The id of the KeyStore for this key object
243
QString storeId() const;
246
Serialize into a string for use as a passive entry
248
QString toString() const;
251
Load a passive entry by using a serialized string
254
\param serialized the string containing the keystore entry information
256
\return the newly created KeyStoreEntry
258
static KeyStoreEntry fromString(const QString &serialized);
261
If a KeyBundle is stored in this object, return that
264
KeyBundle keyBundle() const;
267
If a Certificate is stored in this object, return that
270
Certificate certificate() const;
273
If a CRL is stored in this object, return the value
279
If the key stored in this object is a private
280
PGP key, return the contents of that key.
282
PGPKey pgpSecretKey() const;
285
If the key stored in this object is either an
286
public or private PGP key, extract the public key
287
part of that PGP key.
289
PGPKey pgpPublicKey() const;
292
Returns true if the entry is available, otherwise false.
294
Available means that any private content for this entry is
295
present and ready for use. In the case of a smart card, this
296
will ensure the card is inserted, and may invoke a token
299
Calling this function on an already available entry may cause
300
the entry to be refreshed.
305
\note This function is blocking.
306
\note This synchronous operation may require event handling, and so
307
it must not be called from the same thread as an EventHandler.
309
bool ensureAvailable();
312
Like ensureAvailable, but will also ensure
313
that the PIN is provided if needed.
318
\note This synchronous operation may require event handling, and so
319
it must not be called from the same thread as an EventHandler.
327
friend class KeyStoreTracker;
331
\class KeyStoreEntryWatcher qca_keystore.h QtCrypto
333
Class to monitor the availability of a KeyStoreEntry
335
Some KeyStore types have the concept of an entry that can be
336
available only part of the time (for example, a smart card that
337
can be removed). This class allows you to identify when a
338
KeyStoreEntry becomes available / unavailable.
340
\note You can also monitor availability of a whole KeyStore,
341
using KeyStoreManager::keyStoreAvailable() signal, and
342
the KeyStore::unavailable() signal.
344
\sa KeyStore for more discussion on availability of
345
keys and related objects.
349
class QCA_EXPORT KeyStoreEntryWatcher : public QObject
354
Standard constructor.
356
This creates an object that monitors the specified KeyStore entry,
357
emitting available() and unavailable() as the entry becomes available
358
and unavailable respectively.
360
\param e the KeyStoreEntry to monitor
361
\param parent the parent object for this object
363
explicit KeyStoreEntryWatcher(const KeyStoreEntry &e, QObject *parent = 0);
365
~KeyStoreEntryWatcher();
368
The KeyStoreEntry that is being monitored
370
KeyStoreEntry entry() const;
374
This signal is emitted when the entry that is being monitored
380
This signal is emitted when the entry that is being monitored
386
Q_DISABLE_COPY(KeyStoreEntryWatcher)
389
friend class Private;
394
\class KeyStore qca_keystore.h QtCrypto
396
General purpose key storage object
398
Examples of use of this are:
399
- systemstore: System TrustedCertificates
400
- accepted self-signed: Application TrustedCertificates
401
- apple keychain: User Identities
402
- smartcard: SmartCard Identities
403
- gnupg: PGPKeyring Identities,PGPPublicKeys
406
- there can be multiple KeyStore objects referring to the same id
407
- when a KeyStore is constructed, it refers to a given id (deviceId)
408
and internal contextId. if the context goes away, the KeyStore
409
becomes invalid (isValid() == false), and unavailable() is emitted.
410
even if the device later reappears, the KeyStore remains invalid.
411
a new KeyStore will have to be created to use the device again.
415
class QCA_EXPORT KeyStore : public QObject, public Algorithm
424
System, ///< objects such as root certificates
425
User, ///< objects such as Apple Keychain, KDE Wallet
426
Application, ///< for caching accepted self-signed certificates
427
SmartCard, ///< for smartcards
428
PGPKeyring ///< for a PGP keyring
432
Obtain a specific KeyStore
434
\param id the identification for the key store
435
\param keyStoreManager the parent manager for this keystore
437
KeyStore(const QString &id, KeyStoreManager *keyStoreManager);
442
Check if this KeyStore is valid
444
\return true if the KeyStore is valid
446
bool isValid() const;
454
The name associated with the KeyStore
456
QString name() const;
459
The ID associated with the KeyStore
464
Test if the KeyStore is writeable or not
466
\return true if the KeyStore is read-only
468
bool isReadOnly() const;
471
Turns on asynchronous mode for this KeyStore instance.
473
Normally, entryList() and writeEntry() are blocking
474
calls. However, if startAsynchronousMode() is called,
475
then these functions will return immediately. entryList()
476
will return with the latest known entries, or an empty
477
list if none are known yet (in this mode, updated() will
478
be emitted once the initial entries are known, even if the
479
store has not actually been altered). writeEntry() will
480
always return an empty string, and the entryWritten()
481
signal indicates the result of a write.
483
void startAsynchronousMode();
486
A list of the KeyStoreEntry objects in this store
488
\note This synchronous operation may require event handling, and so
489
it must not be called from the same thread as an EventHandler
490
(this is not a concern if asynchronous mode is enabled).
492
\sa startAsynchronousMode
494
QList<KeyStoreEntry> entryList() const;
497
test if the KeyStore holds trusted certificates (and CRLs)
499
bool holdsTrustedCertificates() const;
502
test if the KeyStore holds identities (eg KeyBundle or PGPSecretKey)
504
bool holdsIdentities() const;
507
test if the KeyStore holds PGPPublicKey objects
509
bool holdsPGPPublicKeys() const;
512
Add a entry to the KeyStore
514
Returns the entryId of the written entry or an empty
517
\param kb the KeyBundle to add to the KeyStore
519
\note This synchronous operation may require event handling, and so
520
it must not be called from the same thread as an EventHandler
521
(this is not a concern if asynchronous mode is enabled).
523
\sa startAsynchronousMode
525
QString writeEntry(const KeyBundle &kb);
530
\param cert the Certificate to add to the KeyStore
532
QString writeEntry(const Certificate &cert);
537
\param crl the CRL to add to the KeyStore
539
QString writeEntry(const CRL &crl);
544
\param key the PGPKey to add to the KeyStore
546
\return a ref to the key in the keyring
548
QString writeEntry(const PGPKey &key);
551
Delete the a specified KeyStoreEntry from this KeyStore
553
\param id the ID for the entry to be deleted
555
\note This synchronous operation may require event handling, and so
556
it must not be called from the same thread as an EventHandler
557
(this is not a concern if asynchronous mode is enabled).
559
\sa startAsynchronousMode
561
bool removeEntry(const QString &id);
565
Emitted when the KeyStore is changed
567
This occurs if entries are added, removed, or changed in this
568
KeyStore, including changes in entry availability.
573
Emitted when the KeyStore becomes unavailable
578
Emitted when an entry has been written, in asynchronous
581
\param entryId is the newly written entry id on success,
582
or an empty string if the write failed.
584
void entryWritten(const QString &entryId);
587
Emitted when an entry has been removed, in asynchronous
590
\param success indicates if the removal succeeded (true) or not (false).
592
void entryRemoved(bool success);
595
Q_DISABLE_COPY(KeyStore)
597
friend class KeyStorePrivate;
600
friend class KeyStoreManagerPrivate;
604
\class KeyStoreInfo qca_keystore.h QtCrypto
606
Key store information, outside of a KeyStore object
608
This class is used in conjunction with the Event class,
609
and related classes such as PasswordAsker and TokenAsker,
610
to describe the key store source of the Event.
612
Each KeyStoreInfo represents a single KeyStore, and describes
613
the type of store (e.g. smartcard or PGP keyring - see
614
KeyStore::Type), and a couple of names. The id() of a KeyStore
615
is used to reference it, and is typically of the form
616
"qca-mystorename". The name() of a KeyStore is used to describe
617
it (i.e. this is the "pretty" name to show the user), and is
618
typically of the form "My Store Name".
622
class QCA_EXPORT KeyStoreInfo
628
\note This form of constructor for KeyStoreInfo
629
produces an object that does not describe any
630
KeyStore, and isNull() will return true.
635
Standard constructor.
637
This builds a KeyStoreInfo object that descibes a
640
\param type the type of KeyStore
641
\param id the identification of the KeyStore
642
\param name the descriptive name of the KeyStore
644
KeyStoreInfo(KeyStore::Type type, const QString &id, const QString &name);
649
\param from the KeyStoreInfo to copy from
651
KeyStoreInfo(const KeyStoreInfo &from);
658
\param from the KeyStoreInfo to copy from
660
KeyStoreInfo & operator=(const KeyStoreInfo &from);
663
Test if this object is valid
665
\return true if the object is not valid
670
The Type of KeyStore that this KeyStoreInfo object
673
KeyStore::Type type() const;
676
The unique identification of the KeyStore that
677
this KeyStoreInfo object describes.
682
The descriptive name of the KeyStore that this
683
KeyStoreInfo object describes.
685
QString name() const;
689
QSharedDataPointer<Private> d;
693
\class KeyStoreManager qca_keystore.h QtCrypto
695
Access keystores, and monitor keystores for changes.
697
Before you can access a KeyStore, you must create a
698
KeyStoreManager. You then need to start()
699
the KeyStoreManager, and either wait for the busyFinished()
700
signal, or block using waitForBusyFinished().
702
If you know the KeyStoreEntry that you need, you can
703
use KeyStore passively, as described in the KeyStoreEntry
708
class QCA_EXPORT KeyStoreManager : public QObject
713
Create a new KeyStoreManager
715
\param parent the parent for this object
717
KeyStoreManager(QObject *parent = 0);
721
Initialize all key store providers
726
Initialize a specific key store provider
728
\param provider the name of the provider to start
730
static void start(const QString &provider);
733
Indicates if the manager is busy looking for key stores
738
Blocks until the manager is done looking for key stores
740
void waitForBusyFinished();
743
A list of all the key stores
745
QStringList keyStores() const;
748
The diagnostic result of key store operations, such as
751
static QString diagnosticText();
754
Clears the diagnostic result log
756
static void clearDiagnosticText();
759
If you are not using the eventloop, call this to update
760
the object state to the present
766
emitted when the manager has started looking for key stores
771
emitted when the manager has finished looking for key stores
776
emitted when a new key store becomes available
778
\param id the name of the key store that has become available
780
void keyStoreAvailable(const QString &id);
783
Q_DISABLE_COPY(KeyStoreManager)
785
friend class KeyStoreManagerPrivate;
786
KeyStoreManagerPrivate *d;
789
friend class KeyStorePrivate;
792
static void shutdown();
added
removed
third-party/qca/qca/include/QtCrypto/qca_keystore.h
