Okular

signatureutils.h
1 /*
2  SPDX-FileCopyrightText: 2018 Chinmoy Ranjan Pradhan <[email protected]>
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 
18 namespace Okular
19 {
20 
21 /**
22  * @short A helper class to store information about x509 certificate
23  */
24 class CertificateInfoPrivate;
25 class OKULARCORE_EXPORT CertificateInfo
26 {
27 public:
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 {
58  CommonName,
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  /**
70  * Destructor
71  */
72  ~CertificateInfo();
73 
74  /**
75  * Returns true if the certificate has no contents; otherwise returns false
76  * @since 23.08
77  */
78  bool isNull() const;
79 
80  /**
81  * Sets the null value of the certificate.
82  * @since 23.08
83  */
84  void setNull(bool null);
85 
86  /**
87  * The certificate version string.
88  * @since 23.08
89  */
90  int version() const;
91 
92  /**
93  * Sets the certificate version string.
94  * @since 23.08
95  */
96  void setVersion(int version);
97 
98  /**
99  * The certificate serial number.
100  * @since 23.08
101  */
102  QByteArray serialNumber() const;
103 
104  /**
105  * Sets the certificate serial number.
106  * @since 23.08
107  */
108  void setSerialNumber(const QByteArray &serial);
109 
110  /**
111  * Information about the issuer.
112  * @since 23.08
113  */
114  QString issuerInfo(EntityInfoKey key, EmptyString empty) const;
115 
116  /**
117  * Sets information about the issuer.
118  * @since 23.08
119  */
120  void setIssuerInfo(EntityInfoKey key, const QString &value);
121 
122  /**
123  * Information about the subject
124  * @since 23.08
125  */
126  QString subjectInfo(EntityInfoKey key, EmptyString empty) const;
127 
128  /**
129  * Sets information about the subject
130  * @since 23.08
131  */
132  void setSubjectInfo(EntityInfoKey key, const QString &value);
133 
134  /**
135  * The certificate internal database nickname
136  * @since 23.08
137  */
138  QString nickName() const;
139 
140  /**
141  * Sets the certificate internal database nickname
142  * @since 23.08
143  */
144  void setNickName(const QString &nickName);
145 
146  /**
147  * The date-time when certificate becomes valid.
148  * @since 23.08
149  */
150  QDateTime validityStart() const;
151 
152  /**
153  * Sets the date-time when certificate becomes valid.
154  * @since 23.08
155  */
156  void setValidityStart(const QDateTime &start);
157 
158  /**
159  * The date-time when certificate expires.
160  * @since 23.08
161  */
162  QDateTime validityEnd() const;
163 
164  /**
165  * Sets the date-time when certificate expires.
166  * @since 23.08
167  */
168  void setValidityEnd(const QDateTime &validityEnd);
169 
170  /**
171  * The uses allowed for the certificate.
172  * @since 23.08
173  */
174  KeyUsageExtensions keyUsageExtensions() const;
175 
176  /**
177  * Sets the uses allowed for the certificate.
178  * @since 23.08
179  */
180  void setKeyUsageExtensions(KeyUsageExtensions ext);
181 
182  /**
183  * The public key value.
184  * @since 23.08
185  */
186  QByteArray publicKey() const;
187  /**
188  * Sets the public key value.
189  * @since 23.08
190  */
191  void setPublicKey(const QByteArray &publicKey);
192 
193  /**
194  * The public key type.
195  * @since 23.08
196  */
197  PublicKeyType publicKeyType() const;
198 
199  /**
200  * Sets the public key type.
201  * @since 23.08
202  */
203  void setPublicKeyType(PublicKeyType type);
204 
205  /**
206  * The strength of public key in bits.
207  * @since 23.08
208  */
209  int publicKeyStrength() const;
210 
211  /**
212  * Sets the strength of strength key in bits.
213  * @since 23.08
214  */
215  void setPublicKeyStrength(int strength);
216 
217  /**
218  * Returns true if certificate is self-signed otherwise returns false.
219  * @since 23.08
220  */
221  bool isSelfSigned() const;
222 
223  /**
224  * Sets if certificate is self-signed
225  * @since 23.08
226  */
227  void setSelfSigned(bool selfSigned);
228 
229  /**
230  * The DER encoded certificate.
231  * @since 23.08
232  */
233  QByteArray certificateData() const;
234 
235  /**
236  * Sets the DER encoded certificate.
237  * @since 23.08
238  */
239  void setCertificateData(const QByteArray &certificateData);
240 
241  /**
242  * The backend where the certificate originates.
243  * see @ref Backend for details
244  * @since 23.08
245  */
246  Backend backend() const;
247 
248  /**
249  * Sets the backend for this certificate.
250  * see @ref Backend for details
251  * @since 23.08
252  */
253  void setBackend(Backend backend);
254 
255  /**
256  * Checks if the given password is the correct one for this certificate
257  *
258  * @since 23.08
259  */
260  bool checkPassword(const QString &password) const;
261 
262  /**
263  * Sets a function to check if the current password is correct.
264  *
265  * The default reject all passwords
266  *
267  * @since 23.08
268  */
269  void setCheckPasswordFunction(const std::function<bool(const QString &)> &passwordFunction);
270 
271  CertificateInfo();
272  CertificateInfo(const CertificateInfo &other);
273  CertificateInfo(CertificateInfo &&other) noexcept;
274  CertificateInfo &operator=(const CertificateInfo &other);
275  CertificateInfo &operator=(CertificateInfo &&other) noexcept;
276 
277 private:
279 };
280 
281 /**
282  * @short A helper class to store information about digital signature
283  */
284 class SignatureInfoPrivate;
285 class OKULARCORE_EXPORT SignatureInfo
286 {
287 public:
288  /**
289  * The verification result of the signature.
290  */
291  enum SignatureStatus {
292  SignatureStatusUnknown, ///< The signature status is unknown for some reason.
293  SignatureValid, ///< The signature is cryptographically valid.
294  SignatureInvalid, ///< The signature is cryptographically invalid.
295  SignatureDigestMismatch, ///< The document content was changed after the signature was applied.
296  SignatureDecodingError, ///< The signature CMS/PKCS7 structure is malformed.
297  SignatureGenericError, ///< The signature could not be verified.
298  SignatureNotFound, ///< The requested signature is not present in the document.
299  SignatureNotVerified ///< The signature is not yet verified.
300  };
301 
302  /**
303  * The verification result of the certificate.
304  */
305  enum CertificateStatus {
306  CertificateStatusUnknown, ///< The certificate status is unknown for some reason.
307  CertificateTrusted, ///< The certificate is considered trusted.
308  CertificateUntrustedIssuer, ///< The issuer of this certificate has been marked as untrusted by the user.
309  CertificateUnknownIssuer, ///< The certificate trust chain has not finished in a trusted root certificate.
310  CertificateRevoked, ///< The certificate was revoked by the issuing certificate authority.
311  CertificateExpired, ///< The signing time is outside the validity bounds of this certificate.
312  CertificateGenericError, ///< The certificate could not be verified.
313  CertificateNotVerified ///< The certificate is not yet verified.
314  };
315 
316  /**
317  * The hash algorithm of the signature
318  */
319  enum HashAlgorithm { HashAlgorithmUnknown, HashAlgorithmMd2, HashAlgorithmMd5, HashAlgorithmSha1, HashAlgorithmSha256, HashAlgorithmSha384, HashAlgorithmSha512, HashAlgorithmSha224 };
320 
321  /**
322  * Destructor.
323  */
324  ~SignatureInfo();
325 
326  /**
327  * The signature status of the signature.
328  * @since 23.08
329  */
330  SignatureStatus signatureStatus() const;
331 
332  /**
333  * Sets the signature status of the signature.
334  * @since 23.08
335  */
336  void setSignatureStatus(SignatureStatus status);
337 
338  /**
339  * The certificate status of the signature.
340  * @since 23.08
341  */
342  CertificateStatus certificateStatus() const;
343 
344  /**
345  * Sets the certificate status of the signature.
346  * @since 23.08
347  */
348  void setCertificateStatus(CertificateStatus status);
349 
350  /**
351  * The signer subject common name associated with the signature.
352  * @since 23.08
353  */
354  QString signerName() const;
355 
356  /**
357  * Sets the signer subject common name associated with the signature.
358  * @since 23.08
359  */
360  void setSignerName(const QString &signerName);
361 
362  /**
363  * The signer subject distinguished name associated with the signature.
364  * @since 23.08
365  */
366  QString signerSubjectDN() const;
367 
368  /**
369  * Sets the signer subject distinguished name associated with the signature.
370  * @since 23.08
371  */
372  void setSignerSubjectDN(const QString &signerSubjectDN);
373 
374  /**
375  * Get signing location.
376  * @since 23.08
377  */
378  QString location() const;
379 
380  /**
381  * Sets the signing location.
382  * @since 23.08
383  */
384  void setLocation(const QString &location);
385 
386  /**
387  * Get signing reason.
388  * @since 23.08
389  */
390  QString reason() const;
391 
392  /**
393  * Sets the signing reason.
394  * @since 23.08
395  */
396  void setReason(const QString &reason);
397 
398  /**
399  * The hash algorithm used for the signature.
400  * @since 23.08
401  */
402  HashAlgorithm hashAlgorithm() const;
403 
404  /**
405  * Sets the hash algorithm used for the signature.
406  * @since 23.08
407  */
408  void setHashAlgorithm(HashAlgorithm algorithm);
409 
410  /**
411  * The signing time associated with the signature.
412  * @since 23.08
413  */
414  QDateTime signingTime() const;
415 
416  /**
417  * Sets the signing time associated with the signature.
418  * @since 23.08
419  */
420  void setSigningTime(const QDateTime &time);
421 
422  /**
423  * Get the signature binary data.
424  * @since 23.08
425  */
426  QByteArray signature() const;
427 
428  /**
429  * Sets the signature binary data.
430  * @since 23.08
431  */
432  void setSignature(const QByteArray &signature);
433 
434  /**
435  * Get the bounds of the ranges of the document which are signed.
436  * @since 23.08
437  */
438  QList<qint64> signedRangeBounds() const;
439 
440  /**
441  * Sets the bounds of the ranges of the document which are signed.
442  * @since 23.08
443  */
444  void setSignedRangeBounds(const QList<qint64> &range);
445 
446  /**
447  * Checks whether the signature authenticates the total document
448  * except for the signature itself.
449  * @since 23.08
450  */
451  bool signsTotalDocument() const;
452 
453  /**
454  * Checks whether the signature authenticates the total document
455  * except for the signature itself.
456  * @since 23.08
457  */
458  void setSignsTotalDocument(bool total);
459 
460  /**
461  * Get certificate details.
462  * @since 23.08
463  */
464  CertificateInfo certificateInfo() const;
465 
466  /**
467  * Sets certificate details.
468  * @since 23.08
469  */
470  void setCertificateInfo(const CertificateInfo &info);
471 
472  SignatureInfo();
473  SignatureInfo(const SignatureInfo &other);
474  SignatureInfo(SignatureInfo &&other) noexcept;
475  SignatureInfo &operator=(const SignatureInfo &other);
476  SignatureInfo &operator=(SignatureInfo &&other) noexcept;
477 
478 private:
480 };
481 
482 /**
483  * @short A helper class to store information about x509 certificate
484  */
485 class OKULARCORE_EXPORT CertificateStore
486 {
487 public:
488  /**
489  * Destructor
490  */
491  virtual ~CertificateStore();
492 
493  /**
494  * Returns list of valid, usable signing certificates.
495  *
496  * This can ask the user for a password, userCancelled will be true if the user decided not to enter it.
497  * @since 23.08
498  */
499  virtual QList<CertificateInfo> signingCertificates(bool *userCancelled) const;
500 
501  /**
502  * Returns list of valid, usable signing certificates for current date and time.
503  *
504  * This can ask the user for a password, userCancelled will be true if the user decided not to enter it.
505  *
506  * nonDateValidCerts is true if the user has signing certificates but their validity start date is in the future or past their validity end date.
507  * @since 23.08
508  */
509  QList<CertificateInfo> signingCertificatesForNow(bool *userCancelled, bool *nonDateValidCerts) const;
510 
511 protected:
513 
514 private:
515  Q_DISABLE_COPY(CertificateStore)
516 };
517 
518 }
519 
520 #endif
QVariant location(const QVariant &res)
A helper class to store information about x509 certificate.
The documentation to the global Okular namespace.
Definition: action.h:16
CommonName
Q_SCRIPTABLE Q_NOREPLY void start()
Q_SCRIPTABLE CaptureState status()
KDB_EXPORT KDbVersionInfo version()
Organization
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Sep 27 2023 03:53:51 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.