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 CertificateVerificationInProgress, ///< The certification is not yet verified, but in progress \since 24.08
345 };
346
347 /**
348 * The hash algorithm of the signature
349 */
350 enum HashAlgorithm { HashAlgorithmUnknown, HashAlgorithmMd2, HashAlgorithmMd5, HashAlgorithmSha1, HashAlgorithmSha256, HashAlgorithmSha384, HashAlgorithmSha512, HashAlgorithmSha224 };
351
352 /**
353 * Destructor.
354 */
355 ~SignatureInfo();
356
357 /**
358 * The signature status of the signature.
359 * @since 23.08
360 */
361 SignatureStatus signatureStatus() const;
362
363 /**
364 * Sets the signature status of the signature.
365 * @since 23.08
366 */
367 void setSignatureStatus(SignatureStatus status);
368
369 /**
370 * The certificate status of the signature.
371 * @since 23.08
372 */
373 CertificateStatus certificateStatus() const;
374
375 /**
376 * Sets the certificate status of the signature.
377 * @since 23.08
378 */
379 void setCertificateStatus(CertificateStatus status);
380
381 /**
382 * The signer subject common name associated with the signature.
383 * @since 23.08
384 */
385 QString signerName() const;
386
387 /**
388 * Sets the signer subject common name associated with the signature.
389 * @since 23.08
390 */
391 void setSignerName(const QString &signerName);
392
393 /**
394 * The signer subject distinguished name associated with the signature.
395 * @since 23.08
396 */
397 QString signerSubjectDN() const;
398
399 /**
400 * Sets the signer subject distinguished name associated with the signature.
401 * @since 23.08
402 */
403 void setSignerSubjectDN(const QString &signerSubjectDN);
404
405 /**
406 * Get signing location.
407 * @since 23.08
408 */
409 QString location() const;
410
411 /**
412 * Sets the signing location.
413 * @since 23.08
414 */
415 void setLocation(const QString &location);
416
417 /**
418 * Get signing reason.
419 * @since 23.08
420 */
421 QString reason() const;
422
423 /**
424 * Sets the signing reason.
425 * @since 23.08
426 */
427 void setReason(const QString &reason);
428
429 /**
430 * The hash algorithm used for the signature.
431 * @since 23.08
432 */
433 HashAlgorithm hashAlgorithm() const;
434
435 /**
436 * Sets the hash algorithm used for the signature.
437 * @since 23.08
438 */
439 void setHashAlgorithm(HashAlgorithm algorithm);
440
441 /**
442 * The signing time associated with the signature.
443 * @since 23.08
444 */
445 QDateTime signingTime() const;
446
447 /**
448 * Sets the signing time associated with the signature.
449 * @since 23.08
450 */
451 void setSigningTime(const QDateTime &time);
452
453 /**
454 * Get the signature binary data.
455 * @since 23.08
456 */
457 QByteArray signature() const;
458
459 /**
460 * Sets the signature binary data.
461 * @since 23.08
462 */
463 void setSignature(const QByteArray &signature);
464
465 /**
466 * Get the bounds of the ranges of the document which are signed.
467 * @since 23.08
468 */
469 QList<qint64> signedRangeBounds() const;
470
471 /**
472 * Sets the bounds of the ranges of the document which are signed.
473 * @since 23.08
474 */
475 void setSignedRangeBounds(const QList<qint64> &range);
476
477 /**
478 * Checks whether the signature authenticates the total document
479 * except for the signature itself.
480 * @since 23.08
481 */
482 bool signsTotalDocument() const;
483
484 /**
485 * Checks whether the signature authenticates the total document
486 * except for the signature itself.
487 * @since 23.08
488 */
489 void setSignsTotalDocument(bool total);
490
491 /**
492 * Get certificate details.
493 * @since 23.08
494 */
495 CertificateInfo certificateInfo() const;
496
497 /**
498 * Sets certificate details.
499 * @since 23.08
500 */
501 void setCertificateInfo(const CertificateInfo &info);
502
503 SignatureInfo();
504 SignatureInfo(const SignatureInfo &other);
505 SignatureInfo(SignatureInfo &&other) noexcept;
506 SignatureInfo &operator=(const SignatureInfo &other);
507 SignatureInfo &operator=(SignatureInfo &&other) noexcept;
508
509private:
511};
512
513/**
514 * @short A helper class to store information about x509 certificate
515 */
516class OKULARCORE_EXPORT CertificateStore
517{
518public:
519 /**
520 * Destructor
521 */
522 virtual ~CertificateStore();
523
524 /**
525 * Returns list of valid, usable signing certificates.
526 *
527 * This can ask the user for a password, userCancelled will be true if the user decided not to enter it.
528 * @since 23.08
529 */
530 virtual QList<CertificateInfo> signingCertificates(bool *userCancelled) const;
531
532 /**
533 * Returns list of valid, usable signing certificates for current date and time.
534 *
535 * This can ask the user for a password, userCancelled will be true if the user decided not to enter it.
536 *
537 * nonDateValidCerts is true if the user has signing certificates but their validity start date is in the future or past their validity end date.
538 * @since 23.08
539 */
540 QList<CertificateInfo> signingCertificatesForNow(bool *userCancelled, bool *nonDateValidCerts) const;
541
542protected:
544
545private:
546 Q_DISABLE_COPY(CertificateStore)
547};
548
549}
550
551#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
CertificateRevoked
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Jul 12 2024 11:57:22 by doxygen 1.11.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.