QCA::KeyStoreEntry Class Reference
[QCA user API]

Single entry in a KeyStore. More...

#include <QtCrypto>

Inheritance diagram for QCA::KeyStoreEntry:

[legend]

List of all members.

Public Types
enum	Type {   TypeKeyBundle, TypeCertificate, TypeCRL, TypePGPSecretKey,   TypePGPPublicKey }
Public Member Functions
	KeyStoreEntry (const KeyStoreEntry &from)
	KeyStoreEntry (const QString &serialized)
	KeyStoreEntry ()
	~KeyStoreEntry ()
Certificate	certificate () const
CRL	crl () const
bool	ensureAccess ()
bool	ensureAvailable ()
QString	id () const
bool	isAccessible () const
bool	isAvailable () const
bool	isNull () const
KeyBundle	keyBundle () const
QString	name () const
KeyStoreEntry &	operator= (const KeyStoreEntry &from)
PGPKey	pgpPublicKey () const
PGPKey	pgpSecretKey () const
QString	storeId () const
QString	storeName () const
QString	toString () const
Type	type () const
Static Public Member Functions
static KeyStoreEntry	fromString (const QString &serialized)

---

Detailed Description

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 objects are obtained through KeyStore or loaded from a serialized string format. The latter method requires a KeyStoreEntry obtained through KeyStore to be serialized for future loading. For example:

QString str = someKeyStoreEntry.toString();
[ app saves str to disk ]
[ app quits ]
...
[ app launches ]
[ app reads str from disk ]
KeyStoreEntry entry(str);
printf("Entry name: [%s]\n", qPrintable(entry.name()));

KeyStoreEntry objects may or may not be available. An entry is unavailable if it has a private content that is not present. The private content might exist on external hardware. To determine if an entry is available, call isAvailable(). To ensure an entry is available before performing a private key operation, call ensureAvailable. For example:

if(entry.ensureAvailable())
{
   entry.keyBundle().privateKey().signMessage(...);
   ...
}

ensureAvailable() blocks and may cause hardware access, but if it completes successfully then you may use the entry's private content. It also means, in the case of a Smart Card token, that it is probably inserted.

To watch this entry asynchronously, you would do:

KeyStoreEntryWatcher *watcher = new KeyStoreEntryWatcher(entry);
connect(watcher, SIGNAL(available()), SLOT(entry_available()));
...
void entry_available()
{
   // entry now available
   watcher->entry().keyBundle().privateKey().signMessage(...);
}

Unlike private content, public content is always usable even if the entry is not available. Serialized entry data contains all of the metadata necessary to reconstruct the public content.

Now, even though an entry may be available, it does not mean you have access to use it for operations. For example, even though a KeyBundle entry offered by a Smart Card may be available, 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:

if(entry.ensureAccess())
{
   // do private key stuff
   ...
}

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:

1) Construct KeyStoreEntry from the serialized data. 2) If the content object is not available, wait for it (with either ensureAvailable() or KeyStoreEntryWatcher). 3) 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. Omit step 2 and the private key operations might cause token prompting.

Definition at line 140 of file qca_keystore.h.

---

Member Enumeration Documentation

enum QCA::KeyStoreEntry::Type

The type of entry in the KeyStore.

Enumerator:

TypeKeyBundle
TypeCertificate
TypeCRL
TypePGPSecretKey
TypePGPPublicKey

Definition at line 146 of file qca_keystore.h.

---

Constructor & Destructor Documentation

QCA::KeyStoreEntry::KeyStoreEntry

(

)

Create an empty KeyStoreEntry.

Definition at line 675 of file qca_keystore.cpp.

QCA::KeyStoreEntry::KeyStoreEntry

(

const QString &

serialized

)

Create a passive KeyStoreEntry based on a serialized string.

Parameters:

serialized

the string containing the keystore entry information

See also:

fromString

Definition at line 680 of file qca_keystore.cpp.

QCA::KeyStoreEntry::KeyStoreEntry

(

const KeyStoreEntry &

from

)

Standard copy constructor.

Parameters:

from

the source entry

Definition at line 686 of file qca_keystore.cpp.

QCA::KeyStoreEntry::~KeyStoreEntry

(

)

Definition at line 691 of file qca_keystore.cpp.

---

Member Function Documentation

Certificate QCA::KeyStoreEntry::certificate

(

)

const

If a Certificate is stored in this object, return that certificate.

Definition at line 762 of file qca_keystore.cpp.

CRL QCA::KeyStoreEntry::crl

(

)

const

If a CRL is stored in this object, return the value of the CRL.

Definition at line 767 of file qca_keystore.cpp.

bool QCA::KeyStoreEntry::ensureAccess

(

)

Like ensureAvailable, but will also ensure that the PIN is provided if needed.

See also:

isAccessible

ensureAvailable

Note:

This synchronous operation may require event handling, and so it must not be called from the same thread as an EventHandler.

Definition at line 792 of file qca_keystore.cpp.

bool QCA::KeyStoreEntry::ensureAvailable

(

)

Returns true if the entry is available, otherwise false.

Available means that any private content for this entry is present and ready for use. In the case of a smart card, this will ensure the card is inserted, and may invoke a token prompt.

Calling this function on an already available entry may cause the entry to be refreshed.

See also:

isAvailable

ensureAccess

Note:

This function is blocking.

This synchronous operation may require event handling, and so it must not be called from the same thread as an EventHandler.

Definition at line 782 of file qca_keystore.cpp.

KeyStoreEntry QCA::KeyStoreEntry::fromString

(

const QString &

serialized

)

[static]

Load a passive entry by using a serialized string as input.

Parameters:

serialized

the string containing the keystore entry information

Returns:

the newly created KeyStoreEntry

Definition at line 748 of file qca_keystore.cpp.

QString QCA::KeyStoreEntry::id

(

)

const

The ID associated with the key stored in this object.

Definition at line 728 of file qca_keystore.cpp.

bool QCA::KeyStoreEntry::isAccessible

(

)

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).

See also:

ensureAccessible

isAvailable

Definition at line 713 of file qca_keystore.cpp.

bool QCA::KeyStoreEntry::isAvailable

(

)

const

Test if the key is available for use.

A key is considered available if the key's private content is present.

See also:

ensureAvailable

isAccessible

Definition at line 708 of file qca_keystore.cpp.

bool QCA::KeyStoreEntry::isNull

(

)

const

Test if this key is empty (null).

Definition at line 703 of file qca_keystore.cpp.

KeyBundle QCA::KeyStoreEntry::keyBundle

(

)

const

If a KeyBundle is stored in this object, return that bundle.

Definition at line 757 of file qca_keystore.cpp.

QString QCA::KeyStoreEntry::name

(

)

const

The name associated with the key stored in this object.

Definition at line 723 of file qca_keystore.cpp.

KeyStoreEntry & QCA::KeyStoreEntry::operator=

(

const KeyStoreEntry &

from

)

Standard assignment operator.

Parameters:

from

the source entry

Reimplemented from QCA::Algorithm.

Definition at line 696 of file qca_keystore.cpp.

PGPKey QCA::KeyStoreEntry::pgpPublicKey

(

)

const

If the key stored in this object is either an public or private PGP key, extract the public key part of that PGP key.

Definition at line 777 of file qca_keystore.cpp.

PGPKey QCA::KeyStoreEntry::pgpSecretKey

(

)

const

If the key stored in this object is a private PGP key, return the contents of that key.

Definition at line 772 of file qca_keystore.cpp.

QString QCA::KeyStoreEntry::storeId

(

)

const

The id of the KeyStore for this key object.

See also:

KeyStore::id()

Definition at line 738 of file qca_keystore.cpp.

QString QCA::KeyStoreEntry::storeName

(

)

const

The name of the KeyStore for this key object.

Definition at line 733 of file qca_keystore.cpp.

QString QCA::KeyStoreEntry::toString

(

)

const

Serialize into a string for use as a passive entry.

Definition at line 743 of file qca_keystore.cpp.

KeyStoreEntry::Type QCA::KeyStoreEntry::type

(

)

const

Determine the type of key stored in this object.

Reimplemented from QCA::Algorithm.

Definition at line 718 of file qca_keystore.cpp.

---

The documentation for this class was generated from the following files:

• qca_keystore.h
• qca_keystore.cpp