QuasarApp/qca
4
0
Fork 0
mirror of https://github.com/QuasarApp/qca.git synced 2025-04-27 12:04:31 +00:00
Code Issues Projects Releases Wiki Activity

More api documentation.

Browse Source 
svn path=/trunk/kdesupport/qca/; revision=525516
This commit is contained in:
Brad Hards 2006-04-02 11:13:14 +00:00
parent aac5851782
commit db07f8150e
2 changed files with 296 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

277
include/QtCrypto/qca_securemessage.h
View File

@ -241,7 +241,7 @@ namespace QCA
/**
\class SecureMessage qca_securemessage.h QtCrypto
Superclass for secure messages
Class representing a secure message
*/
class QCA_EXPORT SecureMessage : public QObject, public Algorithm
{
@ -261,7 +261,7 @@ namespace QCA
*/
enum SignMode
{
Message,
Message, ///< the message includes the signature
Clearsign, ///< the message is clear signed
Detached ///< the signature is detached
};
@ -308,29 +308,198 @@ namespace QCA
The Type of secure message
*/
Type type() const;
bool canSignMultiple() const; // CMS feature
bool canClearsign() const; // PGP feature
bool canSignAndEncrypt() const; // PGP feature
/**
Test if the message type supports multiple
(parallel) signatures.
\return true if the secure message support multiple
parallel signatures
\note PGP cannot do this - it is primarily a CMS
feature
*/
bool canSignMultiple() const;
/**
True if the SecureMessageSystem can clearsign
messages.
\note CMS cannot clearsign - this is normally only
available for PGP
*/
bool canClearsign() 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 canSignAndEncrypt() const;
void reset();
void setEnableBundleSigner(bool b); // CMS: bundle X.509 certificate chain (default true)
void setEnableSMIMEAttributes(bool b); // CMS: include S/MIME attributes (default true)
/**
Set the Format used for messages
\param f whether to use Binary or Ascii
*/
void setFormat(Format f); // (default Binary)
void setRecipient(const SecureMessageKey &key);
void setRecipients(const SecureMessageKeyList &keys);
void setSigner(const SecureMessageKey &key);
void setSigners(const SecureMessageKeyList &keys);
/**
Start an encryption operation
You will normally use this with some code along
these lines:
\code
encryptingObj.startEncrypt();
encryptingObj.update(message);
// perhaps some more update()s
encryptingObj.end();
\endcode
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.
*/
void startEncrypt();
void startDecrypt(); // if decrypted result is signed (PGP only), it will be verified
/**
Start an decryption operation
You will normally use this with some code along
these lines:
\code
decryptingObj.startEncrypt();
decryptingObj.update(message);
// perhaps some more update()s
decryptingObj.end();
\endcode
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 startDecrypt();
/**
Start a signing operation
You will normally use this with some code along
these lines:
\code
signingObj.startSign(QCA::SecureMessage::Detached)
signingObj.update(message);
// perhaps some more update()s
signingObj.end();
\endcode
You then do either waitForFinished(), or use the
finished() signal, to figure out when you can get
the signature. For Detached format, you get the
signature out using signature(); for other formats
you get the signed message out using read().
\param m the mode that will be used to generate the
signature
*/
void startSign(SignMode m = Message);
/**
Start a verification operation
\param detachedSig the detached signature to
verify. Do not pass a signature for other signature
types.
*/
void startVerify(const QByteArray &detachedSig = QByteArray());
/**
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 startSignAndEncrypt();
/**
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.
\param in the data to process
*/
void update(const QByteArray &in);
/**
Read the available data.
\note For detached signatures, you get the message
back using this method, and get the signature back
using the signature() method.
*/
QByteArray read();
/**
The number of bytes available to be read.
*/
int bytesAvailable() const;
/**
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().
*/
void end();
/**
Block until the operation (encryption, decryption,
signing or verifying) completes.
\param 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.
*/
bool waitForFinished(int msecs = 30000);
bool success() const;
@ -338,7 +507,10 @@ namespace QCA
// sign
/**
The signature on the signed message
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().
*/
QByteArray signature() const;
@ -357,14 +529,47 @@ namespace QCA
\return true if the message was signed.
*/
bool wasSigned() const;
/**
Verify that the message signature is correct.
\return true if the signature is valid for the
message, otherwise return false
*/
bool verifySuccess() const;
/**
Information on the signer for the message
*/
SecureMessageSignature signer() 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).
*/
SecureMessageSignatureList signers() const;
QString diagnosticText() const;
signals:
/**
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().
*/
void readyRead();
/**
This signal is emitted when the message is fully
processed.
*/
void finished();
private:
@ -385,6 +590,19 @@ namespace QCA
~SecureMessageSystem();
protected:
/**
Protected constructor for SecureMessageSystem
classes. You are meant to be using a subclass (such
as OpenPGP or CMS) - you only need to worry about
this class if you are creating a whole new
SecureMessageSystem type.
\param parent the parent object for this object
\param type the name of the Type of
SecureMessageSystem to create
\param provider the provider to use, if a specific
provider is required.
*/
SecureMessageSystem(QObject *parent, const QString &type, const QString &provider);
};
@ -397,6 +615,13 @@ namespace QCA
{
Q_OBJECT
public:
/**
Standard constructor
\param parent the parent object for this object
\param provider the provider to use, if a specific
provider is required
*/
OpenPGP(QObject *parent = 0, const QString &provider = QString());
~OpenPGP();
};
@ -405,15 +630,53 @@ namespace QCA
\class CMS qca_securemessage.h QtCrypto
Cryptographic Message Syntax messaging system
Cryptographic Message Syntax (%CMS) "is used to digitally
sign, digest, authenticate, or encrypt arbitrary message
content. The %CMS describes an encapsulation syntax for
data protection. It supports digital signatures and
encryption. The syntax allows multiple encapsulations; one
encapsulation envelope can be nested inside another.
Likewise, one party can digitally sign some previously
encapsulated data. It also allows arbitrary attributes,
such as signing time, to be signed along with the message
content, and provides for other attributes such as
countersignatures to be associated with a signature." (from
<a href="http://www.ietf.org/rfc/rfc3852.txt">RFC3852</a>
"Cryptographic Message Syntax")
*/
class QCA_EXPORT CMS : public SecureMessageSystem
{
Q_OBJECT
public:
/**
Standard constructor
\param parent the parent object for this object
\param provider the provider to use, if a specific
provider is required
*/
CMS(QObject *parent = 0, const QString &provider = QString());
~CMS();
/**
Set the trusted certificates to use for the
messages built using this CMS object.
\param trusted the collection of trusted
certificates to use
*/
void setTrustedCertificates(const CertificateCollection &trusted);
/**
Set the private keys to use for the messages built
using this CMS object.
Keys are required for decrypting and signing (not
for encrypting or verifying).
\param keys the collection of keys to use
*/
void setPrivateKeys(const SecureMessageKeyList &keys);
};
}

26
include/QtCrypto/qca_support.h
View File

@ -80,17 +80,43 @@ namespace QCA
Private *d;
};
/**
Support class to monitor a file for activity
%FileWatch monitors a specified file for any changes. When
the file changes, the changed() signal is emitted.
*/
class QCA_EXPORT FileWatch : public QObject
{
Q_OBJECT
public:
/**
Standard constructor
\param file the name of the file to watch. If not
in this object, you can set it using setFileName()
\param parent the parent object for this object
*/
FileWatch(const QString &file = QString(), QObject *parent = 0);
~FileWatch();
/**
The name of the file that is being monitored
*/
QString fileName() const;
/**
Change the file being monitored
\param file the name of the file to monitor
*/
void setFileName(const QString &file);
signals:
/**
The changed signal is emitted when the file is
changed (e.g. modified, deleted)
*/
void changed();
private: