|
Packit |
d7e8d0 |
Qt API bindings/wrapper for GPGME
|
|
Packit |
d7e8d0 |
---------------------------------
|
|
Packit |
d7e8d0 |
Based on KF5gpgmepp QGpgME and libkleo/backends/qgpgme
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Please note that QGpgME has a different license (GPL only)
|
|
Packit |
d7e8d0 |
then GPGME itself. See the License secion in this
|
|
Packit |
d7e8d0 |
document for more information.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Overview
|
|
Packit |
d7e8d0 |
--------
|
|
Packit |
d7e8d0 |
QGpgme provides a very high level Qt API around GpgMEpp.
|
|
Packit |
d7e8d0 |
As such it depends on GpgMEpp additionally to GpgME.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
There are two general concepts in QGpgME. Data abstraction
|
|
Packit |
d7e8d0 |
through GpgMEpp's Dataprovider interface and the Job pattern.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Data can be provided with QByteArrayDataProvider or
|
|
Packit |
d7e8d0 |
QIODeviceDataProvider which can be constructed from their
|
|
Packit |
d7e8d0 |
respective types. This means you can pass a QFile, QProcess,
|
|
Packit |
d7e8d0 |
QString, etc.. directly to GPGME.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
To provide a stable API / ABI and because of historic reasons
|
|
Packit |
d7e8d0 |
in libkleo (Where QGpgME was originally developed as an abstract
|
|
Packit |
d7e8d0 |
crypto backend) QGpgME only provides abstract interfaces as
|
|
Packit |
d7e8d0 |
public API while the actual implementation happens in the
|
|
Packit |
d7e8d0 |
private QGpgME prefixed classes.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Usage
|
|
Packit |
d7e8d0 |
-----
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
To use QGpgME first you need to obtain a Protocol class
|
|
Packit |
d7e8d0 |
either for CMS (S/MIME) or OpenPGP. This Protocol class
|
|
Packit |
d7e8d0 |
can then be used to create a Job.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Each Job can be started asynchronusly and emits a result
|
|
Packit |
d7e8d0 |
signal when done. The jobs are deleted automatically
|
|
Packit |
d7e8d0 |
with QObject::deleteLater so they can be started without
|
|
Packit |
d7e8d0 |
result handlers.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
The result signal provides a tuple of objects with the
|
|
Packit |
d7e8d0 |
appropriate result information for this job. For historic
|
|
Packit |
d7e8d0 |
reasons each result signal also includes an AuditLog
|
|
Packit |
d7e8d0 |
and an AuditLog Error. These are only useful for
|
|
Packit |
d7e8d0 |
S/MIME signature validation but are part of other jobs
|
|
Packit |
d7e8d0 |
for API stability reasons.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Some jobs like the verification or decryption jobs have
|
|
Packit |
d7e8d0 |
dedicated result classes. Each result class at least
|
|
Packit |
d7e8d0 |
has the member function error() that can be used
|
|
Packit |
d7e8d0 |
to check if a job failed. Additionally errors are emited
|
|
Packit |
d7e8d0 |
in the result signal.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Jobs also provide progress signal whenever GnuPG emits
|
|
Packit |
d7e8d0 |
a progress status line.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Most jobs also provide a way synchronusly execute them.
|
|
Packit |
d7e8d0 |
Please not that synchronus use does not cause the autodeletion
|
|
Packit |
d7e8d0 |
to take place so you have to manually delete them.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Async usage:
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
/* Create a job */
|
|
Packit |
d7e8d0 |
EncryptJob *job = openpgp()->encryptJob(/*ASCII Armor */false, /* Textmode */ false);
|
|
Packit |
d7e8d0 |
/* Connect something to the result signal */
|
|
Packit |
d7e8d0 |
connect(job, &EncryptJob::result, this, [] (const GpgME::EncryptionResult &result,
|
|
Packit |
d7e8d0 |
const QByteArray &cipherText,
|
|
Packit |
d7e8d0 |
const QString,
|
|
Packit |
d7e8d0 |
const GpgME::Error) {
|
|
Packit |
d7e8d0 |
/* Handle the result / do something with the ciphertext */
|
|
Packit |
d7e8d0 |
});
|
|
Packit |
d7e8d0 |
/* Start the job */
|
|
Packit |
d7e8d0 |
job->start(keys, inptr, outptr, Context::AlwaysTrust);
|
|
Packit |
d7e8d0 |
/* Do not delete the job as it is autodeleted. */
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Synchronous usage:
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
/* Create a job */
|
|
Packit |
d7e8d0 |
KeyListJob *listjob = openpgp()->keyListJob(false, false, false);
|
|
Packit |
d7e8d0 |
/* Prepare result vector */
|
|
Packit |
d7e8d0 |
std::vector<Key> keys;
|
|
Packit |
d7e8d0 |
/* Execute it synchronusly */
|
|
Packit |
d7e8d0 |
KeyListResult result = listjob->exec(QStringList() << QStringLiteral("alfa@example.net"),
|
|
Packit |
d7e8d0 |
false, keys);
|
|
Packit |
d7e8d0 |
/* Delete the job */
|
|
Packit |
d7e8d0 |
delete listjob;
|
|
Packit |
d7e8d0 |
/* Work with the result */
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
See the generated documentation for more info on the classes
|
|
Packit |
d7e8d0 |
in QGpgME. (Subdir doc)
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Examples / Tests
|
|
Packit |
d7e8d0 |
----------------
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
The tests in the tests subdir can be used to get a better
|
|
Packit |
d7e8d0 |
idea of QGpgME's usage. They also serve to test the C++
|
|
Packit |
d7e8d0 |
API. Kleopatra and KMails Messagelib also make extensive
|
|
Packit |
d7e8d0 |
use of QGpgME and can be used as further examples.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
Hacking
|
|
Packit |
d7e8d0 |
-------
|
|
Packit |
d7e8d0 |
QGpgME comes from a KDE background. As such it does not use
|
|
Packit |
d7e8d0 |
GNU Coding styles but KDE Coding styles. See:
|
|
Packit |
d7e8d0 |
https://techbase.kde.org/Policies/Frameworks_Coding_Style
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
License
|
|
Packit |
d7e8d0 |
-------
|
|
Packit |
d7e8d0 |
QGpgME is free software; you can redistribute it and/or
|
|
Packit |
d7e8d0 |
modify it under the terms of the GNU General Public License as
|
|
Packit |
d7e8d0 |
published by the Free Software Foundation; either version 2 of the
|
|
Packit |
d7e8d0 |
License, or (at your option) any later version.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
QGpgME is distributed in the hope that it will be useful,
|
|
Packit |
d7e8d0 |
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit |
d7e8d0 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Packit |
d7e8d0 |
General Public License for more details.
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
You should have received a copy of the GNU General Public License
|
|
Packit |
d7e8d0 |
along with this program; if not, write to the Free Software
|
|
Packit |
d7e8d0 |
Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
|
|
Packit |
d7e8d0 |
|
|
Packit |
d7e8d0 |
In addition, as a special exception, the copyright holders give
|
|
Packit |
d7e8d0 |
permission to link the code of this program with any edition of
|
|
Packit |
d7e8d0 |
the Qt library by Trolltech AS, Norway (or with modified versions
|
|
Packit |
d7e8d0 |
of Qt that use the same license as Qt), and distribute linked
|
|
Packit |
d7e8d0 |
combinations including the two. You must obey the GNU General
|
|
Packit |
d7e8d0 |
Public License in all respects for all of the code used other than
|
|
Packit |
d7e8d0 |
Qt. If you modify this file, you may extend this exception to
|
|
Packit |
d7e8d0 |
your version of the file, but you are not obligated to do so. If
|
|
Packit |
d7e8d0 |
you do not wish to do so, delete this exception statement from
|
|
Packit |
d7e8d0 |
your version.
|