Okular

signatureutils.h
1/*
2 SPDX-FileCopyrightText: 2018 Chinmoy Ranjan Pradhan <chinmoyrp65@gmail.com>
3
4 SPDX-License-Identifier: GPL-2.0-or-later
5*/
6
7#ifndef OKULAR_SIGNATUREUTILS_H
8#define OKULAR_SIGNATUREUTILS_H
9
10#include "okularcore_export.h"
11
12#include <QDateTime>
13#include <QFlag>
14#include <QList>
15#include <QSharedPointer>
16#include <QString>
17
18namespace Okular
19{
20
21/**
22 * @short A helper class to store information about x509 certificate
23 */
24class CertificateInfoPrivate;
25class OKULARCORE_EXPORT CertificateInfo
26{
27public:
28 /** The certificate backend is mostly
29 important if there is a wish to integrate
30 third party viewers, where some third party
31 viewers only interacts with some and not other
32 backend */
33 enum class Backend {
34 /** The backend is either unknown
35 or known, but not something there is
36 currently supported need for*/
37 Unknown,
38 /** The certificates in question originates
39 in gpg and thus can be queried using e.g.
40 KDE's certificate manager Kleopatra */
41 Gpg
42 };
43 /**
44 * The algorithm of public key.
45 */
46 enum PublicKeyType { RsaKey, DsaKey, EcKey, OtherKey };
47
48 /**
49 * Certificate key usage extensions.
50 */
51 enum KeyUsageExtension { KuDigitalSignature = 0x80, KuNonRepudiation = 0x40, KuKeyEncipherment = 0x20, KuDataEncipherment = 0x10, KuKeyAgreement = 0x08, KuKeyCertSign = 0x04, KuClrSign = 0x02, KuEncipherOnly = 0x01, KuNone = 0x00 };
52 Q_DECLARE_FLAGS(KeyUsageExtensions, KeyUsageExtension)
53
54 /**
55 * Predefined keys for elements in an entity's distinguished name.
56 */
57 enum EntityInfoKey {
59 DistinguishedName,
60 EmailAddress,
62 };
63 /**
64 * How should certain empty strings be treated
65 * @since 23.08
66 */
67 enum class EmptyString { /** Empty strings should just be empty*/ Empty, TranslatedNotAvailable /** Empty strings should be a localized version of "Not available" */ };
68
69 /** A signing key can be located in different places
70 * sometimes, for the user, it might be easier to pick
71 * the key located on a card if it have some visual
72 * indicator that it is somehow removable.
73 *
74 * \note a keylocation for a certificate without a private
75 *key (cannot be used for signing) will likely be "Unknown"
76 */
77 enum class KeyLocation {
78 Unknown, /** We don't know the location */
79 Other, /** We know the location, but it is somehow not covered by this enum */
80 Computer, /** The key is on this computer */
81 HardwareToken /** The key is on a dedicated hardware token, either a smartcard or a dedicated usb token (e.g. gnuk, nitrokey or yubikey) */
82 };
83
84 /**
85 * Destructor
86 */
87 ~CertificateInfo();
88
89 /**
90 * Returns true if the certificate has no contents; otherwise returns false
91 * @since 23.08
92 */
93 bool isNull() const;
94
95 /**
96 * Sets the null value of the certificate.
97 * @since 23.08
98 */
99 void setNull(bool null);
100
101 /**
102 * The certificate version string.
103 * @since 23.08
104 */
105 int version() const;
106
107 /**
108 * Sets the certificate version string.
109 * @since 23.08
110 */
111 void setVersion(int version);
112
113 /**
114 * The certificate serial number.
115 * @since 23.08
116 */
117 QByteArray serialNumber() const;
118
119 /**
120 * Sets the certificate serial number.
121 * @since 23.08
122 */
123 void setSerialNumber(const QByteArray &serial);
124
125 /**
126 * Information about the issuer.
127 * @since 23.08
128 */
129 QString issuerInfo(EntityInfoKey key, EmptyString empty) const;
130
131 /**
132 * Sets information about the issuer.
133 * @since 23.08
134 */
135 void setIssuerInfo(EntityInfoKey key, const QString &value);
136
137 /**
138 * Information about the subject
139 * @since 23.08
140 */
141 QString subjectInfo(EntityInfoKey key, EmptyString empty) const;
142
143 /**
144 * Sets information about the subject
145 * @since 23.08
146 */
147 void setSubjectInfo(EntityInfoKey key, const QString &value);
148
149 /**
150 * The certificate internal database nickname
151 * @since 23.08
152 */
153 QString nickName() const;
154
155 /**
156 * Sets the certificate internal database nickname
157 * @since 23.08
158 */
159 void setNickName(const QString &nickName);
160
161 /**
162 * The date-time when certificate becomes valid.
163 * @since 23.08
164 */
165 QDateTime validityStart() const;
166
167 /**
168 * Sets the date-time when certificate becomes valid.
169 * @since 23.08
170 */
171 void setValidityStart(const QDateTime &start);
172
173 /**
174 * The date-time when certificate expires.
175 * @since 23.08
176 */
177 QDateTime validityEnd() const;
178
179 /**
180 * Sets the date-time when certificate expires.
181 * @since 23.08
182 */
183 void setValidityEnd(const QDateTime &validityEnd);
184
185 /**
186 * The uses allowed for the certificate.
187 * @since 23.08
188 */
189 KeyUsageExtensions keyUsageExtensions() const;
190
191 /**
192 * Sets the uses allowed for the certificate.
193 * @since 23.08
194 */
195 void setKeyUsageExtensions(KeyUsageExtensions ext);
196
197 /**
198 * The public key value.
199 * @since 23.08
200 */
201 QByteArray publicKey() const;
202 /**
203 * Sets the public key value.
204 * @since 23.08
205 */
206 void setPublicKey(const QByteArray &publicKey);
207
208 /**
209 * The public key type.
210 * @since 23.08
211 */
212 PublicKeyType publicKeyType() const;
213
214 /**
215 * Sets the public key type.
216 * @since 23.08
217 */
218 void setPublicKeyType(PublicKeyType type);
219
220 /**
221 * The strength of public key in bits.
222 * @since 23.08
223 */
224 int publicKeyStrength() const;
225
226 /**
227 * Sets the strength of strength key in bits.
228 * @since 23.08
229 */
230 void setPublicKeyStrength(int strength);
231
232 /**
233 * Returns true if certificate is self-signed otherwise returns false.
234 * @since 23.08
235 */
236 bool isSelfSigned() const;
237
238 /**
239 * Sets if certificate is self-signed
240 * @since 23.08
241 */
242 void setSelfSigned(bool selfSigned);
243
244 /**
245 * The DER encoded certificate.
246 * @since 23.08
247 */
248 QByteArray certificateData() const;
249
250 /**
251 * Sets the DER encoded certificate.
252 * @since 23.08
253 */
254 void setCertificateData(const QByteArray &certificateData);
255 /*
256 * Sets the location of the certificate
257 *
258 * see \ref KeyLocation enum for details
259 * @since 24.02
260 */
261 void setKeyLocation(KeyLocation location);
262
263 /**
264 * the location of the certificate
265 *
266 * see \ref KeyLocation enum for details
267 * @since 24.02
268 */
269 KeyLocation keyLocation() const;
270
271 /**
272 * The backend where the certificate originates.
273 * see @ref Backend for details
274 * @since 23.08
275 */
276 Backend backend() const;
277
278 /**
279 * Sets the backend for this certificate.
280 * see @ref Backend for details
281 * @since 23.08
282 */
283 void setBackend(Backend backend);
284
285 /**
286 * Checks if the given password is the correct one for this certificate
287 *
288 * @since 23.08
289 */
290 bool checkPassword(const QString &password) const;
291
292 /**
293 * Sets a function to check if the current password is correct.
294 *
295 * The default reject all passwords
296 *
297 * @since 23.08
298 */
299 void setCheckPasswordFunction(const std::function<bool(const QString &)> &passwordFunction);
300
302 CertificateInfo(const CertificateInfo &other);
303 CertificateInfo(CertificateInfo &&other) noexcept;
304 CertificateInfo &operator=(const CertificateInfo &other);
305 CertificateInfo &operator=(CertificateInfo &&other) noexcept;
306
307private:
309};
310
311/**
312 * @short A helper class to store information about digital signature
313 */
314class SignatureInfoPrivate;
315class OKULARCORE_EXPORT SignatureInfo
316{
317public:
318 /**
319 * The verification result of the signature.
320 */
321 enum SignatureStatus {
322 SignatureStatusUnknown, ///< The signature status is unknown for some reason.
323 SignatureValid, ///< The signature is cryptographically valid.
324 SignatureInvalid, ///< The signature is cryptographically invalid.
325 SignatureDigestMismatch, ///< The document content was changed after the signature was applied.
326 SignatureDecodingError, ///< The signature CMS/PKCS7 structure is malformed.
327 SignatureGenericError, ///< The signature could not be verified.
328 SignatureNotFound, ///< The requested signature is not present in the document.
329 SignatureNotVerified ///< The signature is not yet verified.
330 };
331
332 /**
333 * The verification result of the certificate.
334 */
335 enum CertificateStatus {
336 CertificateStatusUnknown, ///< The certificate status is unknown for some reason.
337 CertificateTrusted, ///< The certificate is considered trusted.
338 CertificateUntrustedIssuer, ///< The issuer of this certificate has been marked as untrusted by the user.
339 CertificateUnknownIssuer, ///< The certificate trust chain has not finished in a trusted root certificate.
340 CertificateRevoked, ///< The certificate was revoked by the issuing certificate authority.
341 CertificateExpired, ///< The signing time is outside the validity bounds of this certificate.
342 CertificateGenericError, ///< The certificate could not be verified.
343 CertificateNotVerified ///< The certificate is not yet verified.
344 };
345
346 /**
347 * The hash algorithm of the signature
348 */
349 enum HashAlgorithm { HashAlgorithmUnknown, HashAlgorithmMd2, HashAlgorithmMd5, HashAlgorithmSha1, HashAlgorithmSha256, HashAlgorithmSha384, HashAlgorithmSha512, HashAlgorithmSha224 };
350
351 /**
352 * Destructor.
353 */
354 ~SignatureInfo();
355
356 /**
357 * The signature status of the signature.
358 * @since 23.08
359 */
360 SignatureStatus signatureStatus() const;
361
362 /**
363 * Sets the signature status of the signature.
364 * @since 23.08
365 */
366 void setSignatureStatus(SignatureStatus status);
367
368 /**
369 * The certificate status of the signature.
370 * @since 23.08
371 */
372 CertificateStatus certificateStatus() const;
373
374 /**
375 * Sets the certificate status of the signature.
376 * @since 23.08
377 */
378 void setCertificateStatus(CertificateStatus status);
379
380 /**
381 * The signer subject common name associated with the signature.
382 * @since 23.08
383 */
384 QString signerName() const;
385
386 /**
387 * Sets the signer subject common name associated with the signature.
388 * @since 23.08
389 */
390 void setSignerName(const QString &signerName);
391
392 /**
393 * The signer subject distinguished name associated with the signature.
394 * @since 23.08
395 */
396 QString signerSubjectDN() const;
397
398 /**
399 * Sets the signer subject distinguished name associated with the signature.
400 * @since 23.08
401 */
402 void setSignerSubjectDN(const QString &signerSubjectDN);
403
404 /**
405 * Get signing location.
406 * @since 23.08
407 */
408 QString location() const;
409
410 /**
411 * Sets the signing location.
412 * @since 23.08
413 */
414 void setLocation(const QString &location);
415
416 /**
417 * Get signing reason.
418 * @since 23.08
419 */
420 QString reason() const;
421
422 /**
423 * Sets the signing reason.
424 * @since 23.08
425 */
426 void setReason(const QString &reason);
427
428 /**
429 * The hash algorithm used for the signature.
430 * @since 23.08
431 */
432 HashAlgorithm hashAlgorithm() const;
433
434 /**
435 * Sets the hash algorithm used for the signature.
436 * @since 23.08
437 */
438 void setHashAlgorithm(HashAlgorithm algorithm);
439
440 /**
441 * The signing time associated with the signature.
442 * @since 23.08
443 */
444 QDateTime signingTime() const;
445
446 /**
447 * Sets the signing time associated with the signature.
448 * @since 23.08
449 */
450 void setSigningTime(const QDateTime &time);
451
452 /**
453 * Get the signature binary data.
454 * @since 23.08
455 */
456 QByteArray signature() const;
457
458 /**
459 * Sets the signature binary data.
460 * @since 23.08
461 */
462 void setSignature(const QByteArray &signature);
463
464 /**
465 * Get the bounds of the ranges of the document which are signed.
466 * @since 23.08
467 */
468 QList<qint64> signedRangeBounds() const;
469
470 /**
471 * Sets the bounds of the ranges of the document which are signed.
472 * @since 23.08
473 */
474 void setSignedRangeBounds(const QList<qint64> &range);
475
476 /**
477 * Checks whether the signature authenticates the total document
478 * except for the signature itself.
479 * @since 23.08
480 */
481 bool signsTotalDocument() const;
482
483 /**
484 * Checks whether the signature authenticates the total document
485 * except for the signature itself.
486 * @since 23.08
487 */
488 void setSignsTotalDocument(bool total);
489
490 /**
491 * Get certificate details.
492 * @since 23.08
493 */
494 CertificateInfo certificateInfo() const;
495
496 /**
497 * Sets certificate details.
498 * @since 23.08
499 */
500 void setCertificateInfo(const CertificateInfo &info);
501
502 SignatureInfo();
503 SignatureInfo(const SignatureInfo &other);
504 SignatureInfo(SignatureInfo &&other) noexcept;
505 SignatureInfo &operator=(const SignatureInfo &other);
506 SignatureInfo &operator=(SignatureInfo &&other) noexcept;
507
508private:
510};
511
512/**
513 * @short A helper class to store information about x509 certificate
514 */
515class OKULARCORE_EXPORT CertificateStore
516{
517public:
518 /**
519 * Destructor
520 */
521 virtual ~CertificateStore();
522
523 /**
524 * Returns list of valid, usable signing certificates.
525 *
526 * This can ask the user for a password, userCancelled will be true if the user decided not to enter it.
527 * @since 23.08
528 */
529 virtual QList<CertificateInfo> signingCertificates(bool *userCancelled) const;
530
531 /**
532 * Returns list of valid, usable signing certificates for current date and time.
533 *
534 * This can ask the user for a password, userCancelled will be true if the user decided not to enter it.
535 *
536 * nonDateValidCerts is true if the user has signing certificates but their validity start date is in the future or past their validity end date.
537 * @since 23.08
538 */
539 QList<CertificateInfo> signingCertificatesForNow(bool *userCancelled, bool *nonDateValidCerts) const;
540
541protected:
543
544private:
545 Q_DISABLE_COPY(CertificateStore)
546};
547
548}
549
550#endif
A helper class to store information about x509 certificate.
Q_SCRIPTABLE Q_NOREPLY void start()
Q_SCRIPTABLE CaptureState status()
KDB_EXPORT KDbVersionInfo version()
QVariant location(const QVariant &res)
global.h
Definition action.h:17
CommonName
Organization
QMultiMap< CertificateInfoType, QString > CertificateInfo
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Sun Feb 25 2024 18:44:05 by doxygen 1.10.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.