Qt Cryptographic Architecture: QCA::SecureMessage Class Reference

Qt Cryptographic Architecture

Public Types | Signals | Public Member Functions | Friends | List of all members
QCA::SecureMessage Class Reference
QCA user API

`#include <QtCrypto>`

Collaboration diagram for QCA::SecureMessage:
[legend]

## 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
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 ()
| SecureMessage (SecureMessageSystem *system)
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 QCA::Algorithm
| Algorithm (const Algorithm &from)
void | change (Provider::Context *c)
void | change (const QString &type, const QString &provider)
Provider::Context * | context ()
const Provider::Context * | context () const
Algorithm & | operator= (const Algorithm &from)
Provider * | provider () const
Provider::Context * | takeContext ()
QString | type () const

## Friends
class | Private

## Additional Inherited Members
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.

## Member Enumeration Documentation

## ◆ Type

enum QCA::SecureMessage::Type

The type of secure message.

Enumerator
OpenPGP | a Pretty Good Privacy message
CMS | a Cryptographic Message Syntax message

## ◆ SignMode

enum QCA::SecureMessage::SignMode

The type of message signature.

Enumerator
Message | the message includes the signature
Clearsign | the message is clear signed
Detached | the signature is detached

## ◆ Format

enum QCA::SecureMessage::Format

Formats for secure messages.

Enumerator
Binary | DER/binary.
Ascii | PEM/ascii-armored.

## ◆ Error

enum QCA::SecureMessage::Error

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

## Constructor & Destructor Documentation

## ◆ SecureMessage()

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

  system | a pre-existing and configured SecureMessageSystem object

## Member Function Documentation

## ◆ type()

Type QCA::SecureMessage::type | ( |  | ) | const

The Type of secure message.

## ◆ canSignMultiple()

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

## ◆ canClearsign()

bool QCA::SecureMessage::canClearsign | ( |  | ) | const

True if the SecureMessageSystem can clearsign messages.

Note
  CMS cannot clearsign - this is normally only available for PGP

## ◆ canSignAndEncrypt()

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.

## ◆ reset()

void QCA::SecureMessage::reset | ( |  | ) |

Reset the object state to that of original construction.

Now a new operation can be performed immediately.

## ◆ bundleSignerEnabled()

bool QCA::SecureMessage::bundleSignerEnabled | ( |  | ) | const

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

## ◆ smimeAttributesEnabled()

bool QCA::SecureMessage::smimeAttributesEnabled | ( |  | ) | const

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

## ◆ format()

Format QCA::SecureMessage::format | ( |  | ) | const

Return the format type set for this message.

## ◆ recipientKeys()

SecureMessageKeyList QCA::SecureMessage::recipientKeys | ( |  | ) | const

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

## ◆ signerKeys()

SecureMessageKeyList QCA::SecureMessage::signerKeys | ( |  | ) | const

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

## ◆ setBundleSignerEnabled()

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

  b | whether to bundle (if true) or not (false)

## ◆ setSMIMEAttributesEnabled()

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

  b | whether to embed extra attribues (if true) or not (false)

## ◆ setFormat()

void QCA::SecureMessage::setFormat | ( | Format | f | ) |

Set the Format used for messages.

The default is Binary.

Parameters

  f | whether to use Binary or Ascii

## ◆ setRecipient()

void QCA::SecureMessage::setRecipient | ( | const SecureMessageKey & | key | ) |

Set the recipient for an encrypted message.

Parameters

  key | the recipient's key

See also
  setRecipients

Examples:
  publickeyexample.cpp.

## ◆ setRecipients()

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

  keys | the recipients' key

See also
  setRecipient

## ◆ setSigner()

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

  key | the key associated with the signer

See also
  setSigners

## ◆ 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

  keys | the key associated with the signer

See also
  setSigner

## ◆ startEncrypt()

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.

## ◆ startDecrypt()

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.

## ◆ startSign()

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

  m | the mode that will be used to generate the signature

## ◆ startVerify()

void QCA::SecureMessage::startVerify | ( | const QByteArray & | detachedSig = `QByteArray()` | ) |

Start a verification operation.

Parameters

  detachedSig | the detached signature to verify. Do not pass a signature for other signature types.

## ◆ startSignAndEncrypt()

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.

## ◆ update()

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

  in | the data to process

Examples:
  publickeyexample.cpp.

## ◆ read()

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.

## ◆ bytesAvailable()

int QCA::SecureMessage::bytesAvailable | ( |  | ) | const

The number of bytes available to be read.

## ◆ end()

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.

## ◆ waitForFinished()

bool QCA::SecureMessage::waitForFinished | ( | int | msecs = `30000` | ) |

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

Parameters

  msecs | the 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.

## ◆ success()

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.

## ◆ errorCode()

Error QCA::SecureMessage::errorCode | ( |  | ) | const

Returns the failure code.

See also
  success
  diagnosticText

Examples:
  publickeyexample.cpp.

## ◆ signature()

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

## ◆ hashName()

QString QCA::SecureMessage::hashName | ( |  | ) | const

The name of the hash used for the signature process.

## ◆ wasSigned()

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.

## ◆ verifySuccess()

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

## ◆ signer()

SecureMessageSignature QCA::SecureMessage::signer | ( |  | ) | const

Information on the signer for the message.

## ◆ signers()

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

## ◆ diagnosticText()

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.

## ◆ readyRead

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

## ◆ bytesWritten

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

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

Parameters

  bytes | the number of bytes written

## ◆ finished

void QCA::SecureMessage::finished | ( |  | ) |
| signal

This signal is emitted when the message is fully processed.

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

- qca_securemessage.h