QCA::SecureMessage

#include <QtCrypto>

Inheritance diagram for QCA::SecureMessage:

Public Types

enum  Error {
  ErrorPassphrase, ErrorFormat, ErrorSignerExpired, ErrorSignerInvalid,
  ErrorEncryptExpired, ErrorEncryptUntrusted, ErrorEncryptInvalid, ErrorNeedCard,
  ErrorCertKeyMismatch, ErrorUnknown, ErrorSignerRevoked, ErrorSignatureExpired,
  ErrorEncryptRevoked
}
 
enum  Format { Binary, Ascii }
 
enum  SignMode { Message, Clearsign, Detached }
 
enum  Type { OpenPGP, CMS }
 

Signals

void bytesWritten (int bytes)
 
void finished ()
 
void readyRead ()
 

Public Member Functions

 SecureMessage (SecureMessageSystem *system)
 
bool bundleSignerEnabled () const
 
int bytesAvailable () const
 
bool canClearsign () const
 
bool canSignAndEncrypt () const
 
bool canSignMultiple () const
 
QString diagnosticText () const
 
void end ()
 
Error errorCode () const
 
Format format () const
 
QString hashName () const
 
QByteArray read ()
 
SecureMessageKeyList recipientKeys () const
 
void reset ()
 
void setBundleSignerEnabled (bool b)
 
void setFormat (Format f)
 
void setRecipient (const SecureMessageKey &key)
 
void setRecipients (const SecureMessageKeyList &keys)
 
void setSigner (const SecureMessageKey &key)
 
void setSigners (const SecureMessageKeyList &keys)
 
void setSMIMEAttributesEnabled (bool b)
 
QByteArray signature () const
 
SecureMessageSignature signer () const
 
SecureMessageKeyList signerKeys () const
 
SecureMessageSignatureList signers () const
 
bool smimeAttributesEnabled () const
 
void startDecrypt ()
 
void startEncrypt ()
 
void startSign (SignMode m=Message)
 
void startSignAndEncrypt ()
 
void startVerify (const QByteArray &detachedSig=QByteArray())
 
bool success () const
 
Type type () const
 
void update (const QByteArray &in)
 
bool verifySuccess () const
 
bool waitForFinished (int msecs=30000)
 
bool wasSigned () const
 
- Public Member Functions inherited from QObject
 QObject (QObject *parent)
 
bool blockSignals (bool block)
 
const QObjectListchildren () const const
 
QMetaObject::Connection connect (const QObject *sender, const char *signal, const char *method, Qt::ConnectionType type) const const
 
void deleteLater ()
 
void destroyed (QObject *obj)
 
bool disconnect (const char *signal, const QObject *receiver, const char *method) const const
 
bool disconnect (const QObject *receiver, const char *method) const const
 
void dumpObjectInfo ()
 
void dumpObjectInfo () const const
 
void dumpObjectTree ()
 
void dumpObjectTree () const const
 
QList< QByteArraydynamicPropertyNames () const const
 
virtual bool event (QEvent *e)
 
virtual bool eventFilter (QObject *watched, QEvent *event)
 
findChild (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QString &name, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegExp &regExp, Qt::FindChildOptions options) const const
 
QList< T > findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const
 
bool inherits (const char *className) const const
 
void installEventFilter (QObject *filterObj)
 
bool isWidgetType () const const
 
bool isWindowType () const const
 
void killTimer (int id)
 
virtual const QMetaObjectmetaObject () const const
 
void moveToThread (QThread *targetThread)
 
QString objectName () const const
 
void objectNameChanged (const QString &objectName)
 
QObjectparent () const const
 
QVariant property (const char *name) const const
 
 Q_CLASSINFO (Name, Value)
 
 Q_DISABLE_COPY (Class)
 
 Q_DISABLE_COPY_MOVE (Class)
 
 Q_DISABLE_MOVE (Class)
 
 Q_EMIT Q_EMIT
 
 Q_ENUM (...)
 
 Q_ENUM_NS (...)
 
 Q_ENUMS (...)
 
 Q_FLAG (...)
 
 Q_FLAG_NS (...)
 
 Q_FLAGS (...)
 
 Q_GADGET Q_GADGET
 
 Q_INTERFACES (...)
 
 Q_INVOKABLE Q_INVOKABLE
 
 Q_NAMESPACE Q_NAMESPACE
 
 Q_NAMESPACE_EXPORT (EXPORT_MACRO)
 
 Q_OBJECT Q_OBJECT
 
 Q_PROPERTY (...)
 
 Q_REVISION Q_REVISION
 
 Q_SET_OBJECT_NAME (Object)
 
 Q_SIGNAL Q_SIGNAL
 
 Q_SIGNALS Q_SIGNALS
 
 Q_SLOT Q_SLOT
 
 Q_SLOTS Q_SLOTS
 
qFindChild (const QObject *obj, const QString &name)
 
QList< T > qFindChildren (const QObject *obj, const QRegExp &regExp)
 
QList< T > qFindChildren (const QObject *obj, const QString &name)
 
qobject_cast (QObject *object)
 
qobject_cast (const QObject *object)
 
 QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT
 
void removeEventFilter (QObject *obj)
 
void setObjectName (const QString &name)
 
void setParent (QObject *parent)
 
bool setProperty (const char *name, const QVariant &value)
 
bool signalsBlocked () const const
 
int startTimer (int interval, Qt::TimerType timerType)
 
int startTimer (std::chrono::milliseconds time, Qt::TimerType timerType)
 
QThreadthread () const const
 
- Public Member Functions inherited from QCA::Algorithm
 Algorithm (const Algorithm &from)
 
void change (Provider::Context *c)
 
void change (const QString &type, const QString &provider)
 
Provider::Contextcontext ()
 
const Provider::Contextcontext () const
 
Algorithmoperator= (const Algorithm &from)
 
Providerprovider () const
 
Provider::ContexttakeContext ()
 
QString type () const
 

Additional Inherited Members

- Properties inherited from QObject
 objectName
 
- Static Public Member Functions inherited from QObject
QMetaObject::Connection connect (const QObject *sender, const char *signal, const QObject *receiver, const char *method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method, Qt::ConnectionType type)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)
 
QMetaObject::Connection connect (const QObject *sender, PointerToMemberFunction signal, const QObject *context, Functor functor, Qt::ConnectionType type)
 
bool disconnect (const QMetaObject::Connection &connection)
 
bool disconnect (const QObject *sender, const char *signal, const QObject *receiver, const char *method)
 
bool disconnect (const QObject *sender, PointerToMemberFunction signal, const QObject *receiver, PointerToMemberFunction method)
 
bool disconnect (const QObject *sender, const QMetaMethod &signal, const QObject *receiver, const QMetaMethod &method)
 
QString tr (const char *sourceText, const char *disambiguation, int n)
 
QString trUtf8 (const char *sourceText, const char *disambiguation, int n)
 
- Public Attributes inherited from QObject
typedef QObjectList
 
- Protected Member Functions inherited from QObject
virtual void childEvent (QChildEvent *event)
 
virtual void connectNotify (const QMetaMethod &signal)
 
virtual void customEvent (QEvent *event)
 
virtual void disconnectNotify (const QMetaMethod &signal)
 
bool isSignalConnected (const QMetaMethod &signal) const const
 
int receivers (const char *signal) const const
 
QObjectsender () const const
 
int senderSignalIndex () const const
 
virtual void timerEvent (QTimerEvent *event)
 
- Protected Member Functions inherited from QCA::Algorithm
 Algorithm ()
 
 Algorithm (const QString &type, const QString &provider)
 

Detailed Description

Class representing a secure message.

SecureMessage presents a unified interface for working with both OpenPGP and CMS (S/MIME) messages. Prepare the object by calling setFormat(), setRecipient(), and setSigner() as necessary, and then begin the operation by calling an appropriate 'start' function, such as startSign().

Here is an example of how to perform a Clearsign operation using PGP:

// first make the SecureMessageKey
PGPKey myPGPKey = getSecretKeyFromSomewhere();
SecureMessageKey key;
key.setPGPSecretKey(myPGPKey);
// our data to sign
QByteArray plain = "Hello, world";
// let's do it
OpenPGP pgp;
SecureMessage msg(&pgp);
msg.setSigner(key);
msg.startSign(SecureMessage::Clearsign);
msg.update(plain);
msg.end();
msg.waitForFinished(-1);
if(msg.success())
{
QByteArray result = msg.read();
// result now contains the clearsign text data
}
else
{
// error
...
}

Performing a CMS sign operation is similar. Simply set up the SecureMessageKey with a Certificate instead of a PGPKey, and operate on a CMS object instead of an OpenPGP object.

See also
SecureMessageKey
SecureMessageSignature
OpenPGP
CMS
Examples:
publickeyexample.cpp.

Definition at line 320 of file qca_securemessage.h.

Member Enumeration Documentation

Errors for secure messages.

Enumerator
ErrorPassphrase 

passphrase was either wrong or not provided

ErrorFormat 

input format was bad

ErrorSignerExpired 

signing key is expired

ErrorSignerInvalid 

signing key is invalid in some way

ErrorEncryptExpired 

encrypting key is expired

ErrorEncryptUntrusted 

encrypting key is untrusted

ErrorEncryptInvalid 

encrypting key is invalid in some way

ErrorNeedCard 

pgp card is missing

ErrorCertKeyMismatch 

certificate and private key don't match

ErrorUnknown 

other error

ErrorSignerRevoked 

signing key is revoked

ErrorSignatureExpired 

signature is expired

ErrorEncryptRevoked 

encrypting key is revoked

Definition at line 355 of file qca_securemessage.h.

Formats for secure messages.

Enumerator
Binary 

DER/binary.

Ascii 

PEM/ascii-armored.

Definition at line 346 of file qca_securemessage.h.

The type of message signature.

Enumerator
Message 

the message includes the signature

Clearsign 

the message is clear signed

Detached 

the signature is detached

Definition at line 336 of file qca_securemessage.h.

The type of secure message.

Enumerator
OpenPGP 

a Pretty Good Privacy message

CMS 

a Cryptographic Message Syntax message

Definition at line 327 of file qca_securemessage.h.

Constructor & Destructor Documentation

QCA::SecureMessage::SecureMessage ( SecureMessageSystem system)

Create a new secure message.

This constructor uses an existing SecureMessageSystem object (for example, an OpenPGP or CMS object) to generate a specific kind of secure message.

Parameters
systema pre-existing and configured SecureMessageSystem object

Member Function Documentation

bool QCA::SecureMessage::bundleSignerEnabled ( ) const

Returns true if bundling of the signer certificate chain is enabled.

int QCA::SecureMessage::bytesAvailable ( ) const

The number of bytes available to be read.

void QCA::SecureMessage::bytesWritten ( int  bytes)
signal

This signal is emitted when data has been accepted by the message processor.

Parameters
bytesthe number of bytes written
bool QCA::SecureMessage::canClearsign ( ) const

True if the SecureMessageSystem can clearsign messages.

Note
CMS cannot clearsign - this is normally only available for PGP
bool QCA::SecureMessage::canSignAndEncrypt ( ) const

True if the SecureMessageSystem can both sign and encrypt (in the same operation).

Note
CMS cannot do an integrated sign/encrypt - this is normally only available for PGP. You can do separate signing and encrypting operations on the same message with CMS though.
bool QCA::SecureMessage::canSignMultiple ( ) const

Test if the message type supports multiple (parallel) signatures.

Returns
true if the secure message support multiple parallel signatures
Note
PGP cannot do this - it is primarily a CMS feature
QString QCA::SecureMessage::diagnosticText ( ) const

Returns a log of technical information about the operation, which may be useful for presenting to the user in an advanced error dialog.

void QCA::SecureMessage::end ( )

Complete an operation.

You need to call this method after you have processed the message (which you pass in as the argument to update().

Note
the results of the operation are not available as soon as this method returns. You need to wait for the finished() signal, or use waitForFinished().
Examples:
publickeyexample.cpp.
Error QCA::SecureMessage::errorCode ( ) const

Returns the failure code.

See also
success
diagnosticText
Examples:
publickeyexample.cpp.
void QCA::SecureMessage::finished ( )
signal

This signal is emitted when the message is fully processed.

Format QCA::SecureMessage::format ( ) const

Return the format type set for this message.

QString QCA::SecureMessage::hashName ( ) const

The name of the hash used for the signature process.

QByteArray QCA::SecureMessage::read ( )

Read the available data.

Note
For detached signatures, you don't get anything back using this method. Use signature() to get the detached signature().
Examples:
publickeyexample.cpp.
void QCA::SecureMessage::readyRead ( )
signal

This signal is emitted when there is some data to read.

Typically you connect this signal to a slot that does a read() of the available data.

Note
This signal does not mean that the processing of a message is necessarily complete - see finished().
SecureMessageKeyList QCA::SecureMessage::recipientKeys ( ) const

Return the recipient(s) set for this message with setRecipient() or setRecipients()

void QCA::SecureMessage::reset ( )

Reset the object state to that of original construction.

Now a new operation can be performed immediately.

void QCA::SecureMessage::setBundleSignerEnabled ( bool  b)

For CMS only, this will bundle the signer certificate chain into the message.

This allows a message to be verified on its own, without the need to have obtained the signer's certificate in advance. Email clients using S/MIME often bundle the signer, greatly simplifying key management.

This behavior is enabled by default.

Parameters
bwhether to bundle (if true) or not (false)
void QCA::SecureMessage::setFormat ( Format  f)

Set the Format used for messages.

The default is Binary.

Parameters
fwhether to use Binary or Ascii
void QCA::SecureMessage::setRecipient ( const SecureMessageKey key)

Set the recipient for an encrypted message.

Parameters
keythe recipient's key
See also
setRecipients
Examples:
publickeyexample.cpp.
void QCA::SecureMessage::setRecipients ( const SecureMessageKeyList keys)

Set the list of recipients for an encrypted message.

For a list with one item, this has the same effect as setRecipient.

Parameters
keysthe recipients' key
See also
setRecipient
void QCA::SecureMessage::setSigner ( const SecureMessageKey key)

Set the signer for a signed message.

This is used for both creating signed messages as well as for verifying CMS messages that have no signer bundled.

Parameters
keythe key associated with the signer
See also
setSigners
void QCA::SecureMessage::setSigners ( const SecureMessageKeyList keys)

Set the list of signers for a signed message.

This is used for both creating signed messages as well as for verifying CMS messages that have no signer bundled.

For a list with one item, this has the same effect as setSigner.

Parameters
keysthe key associated with the signer
See also
setSigner
void QCA::SecureMessage::setSMIMEAttributesEnabled ( bool  b)

For CMS only, this will put extra attributes into the message related to S/MIME, such as the preferred type of algorithm to use in replies.

The attributes used are decided by the provider.

This behavior is enabled by default.

Parameters
bwhether to embed extra attribues (if true) or not (false)
QByteArray QCA::SecureMessage::signature ( ) const

The signature for the message.

This is only used for Detached signatures. For other message types, you get the message and signature together using read().

SecureMessageSignature QCA::SecureMessage::signer ( ) const

Information on the signer for the message.

SecureMessageKeyList QCA::SecureMessage::signerKeys ( ) const

Return the signer(s) set for this message with setSigner() or setSigners()

SecureMessageSignatureList QCA::SecureMessage::signers ( ) const

Information on the signers for the message.

This is only meaningful if the message type supports multiple signatures (see canSignMultiple() for a suitable test).

bool QCA::SecureMessage::smimeAttributesEnabled ( ) const

Returns true if inclusion of S/MIME attributes is enabled.

void QCA::SecureMessage::startDecrypt ( )

Start an decryption operation.

You will normally use this with some code along these lines:

decryptingObj.startEncrypt();
decryptingObj.update(message);
// perhaps some more update()s
decryptingObj.end();

Each update() may (or may not) result in some decrypted data, as indicated by the readyRead() signal being emitted. Alternatively, you can wait until the whole message is available (using either waitForFinished(), or the finished() signal). The decrypted message can then be read using the read() method.

Note
If decrypted result is also signed (not for CMS), then the signature will be verified during this operation.
void QCA::SecureMessage::startEncrypt ( )

Start an encryption operation.

You will normally use this with some code along these lines:

encryptingObj.startEncrypt();
encryptingObj.update(message);
// perhaps some more update()s
encryptingObj.end();

Each update() may (or may not) result in some encrypted data, as indicated by the readyRead() signal being emitted. Alternatively, you can wait until the whole message is available (using either waitForFinished(), or use the finished() signal. The encrypted message can then be read using the read() method.

Examples:
publickeyexample.cpp.
void QCA::SecureMessage::startSign ( SignMode  m = Message)

Start a signing operation.

You will normally use this with some code along these lines:

signingObj.startSign(QCA::SecureMessage::Detached)
signingObj.update(message);
// perhaps some more update()s
signingObj.end();

For Detached signatures, you won't get any results until the whole process is done - you either waitForFinished(), or use the finished() signal, to figure out when you can get the signature (using the signature() method, not using read()). For other formats, you can use the readyRead() signal to determine when there may be part of a signed message to read().

Parameters
mthe mode that will be used to generate the signature
void QCA::SecureMessage::startSignAndEncrypt ( )

Start a combined signing and encrypting operation.

You use this in the same way as startEncrypt().

Note
This may not be possible (e.g. CMS cannot do this) - see canSignAndEncrypt() for a suitable test.
void QCA::SecureMessage::startVerify ( const QByteArray detachedSig = QByteArray())

Start a verification operation.

Parameters
detachedSigthe detached signature to verify. Do not pass a signature for other signature types.
bool QCA::SecureMessage::success ( ) const

Indicates whether or not the operation was successful or failed.

If this function returns false, then the reason for failure can be obtained with errorCode().

See also
errorCode
diagnosticText
Examples:
publickeyexample.cpp.
Type QCA::SecureMessage::type ( ) const

The Type of secure message.

void QCA::SecureMessage::update ( const QByteArray in)

Process a message (or the next part of a message) in the current operation.

You need to have already set up the message (startEncrypt(), startDecrypt(), startSign(), startSignAndEncrypt() and startVerify()) before calling this method.

Parameters
inthe data to process
Examples:
publickeyexample.cpp.
bool QCA::SecureMessage::verifySuccess ( ) const

Verify that the message signature is correct.

Returns
true if the signature is valid for the message, otherwise return false
bool QCA::SecureMessage::waitForFinished ( int  msecs = 30000)

Block until the operation (encryption, decryption, signing or verifying) completes.

Parameters
msecsthe number of milliseconds to wait for the operation to complete. Pass -1 to wait indefinitely.
Note
You should not use this in GUI applications where the blocking behaviour looks like a hung application. Instead, connect the finished() signal to a slot that handles the results.
This synchronous operation may require event handling, and so it must not be called from the same thread as an EventHandler.
Examples:
publickeyexample.cpp.
bool QCA::SecureMessage::wasSigned ( ) const

Test if the message was signed.

This is true for OpenPGP if the decrypted message was also signed.

Returns
true if the message was signed.

The documentation for this class was generated from the following file:
This file is part of the KDE documentation.
Documentation copyright © 1996-2020 The KDE developers.
Generated on Thu Aug 6 2020 23:02:40 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.