LCOV - code coverage report
Current view: top level - lang/cpp/src - key.h (source / functions) Hit Total Coverage
Test: coverage.info Lines: 14 30 46.7 %
Date: 2018-11-14 16:53:58 Functions: 11 23 47.8 %

          Line data    Source code
       1             : /*
       2             :   key.h - wraps a gpgme key
       3             :   Copyright (C) 2003, 2005 Klarälvdalens Datakonsult AB
       4             : 
       5             :   This file is part of GPGME++.
       6             : 
       7             :   GPGME++ is free software; you can redistribute it and/or
       8             :   modify it under the terms of the GNU Library General Public
       9             :   License as published by the Free Software Foundation; either
      10             :   version 2 of the License, or (at your option) any later version.
      11             : 
      12             :   GPGME++ is distributed in the hope that it will be useful,
      13             :   but WITHOUT ANY WARRANTY; without even the implied warranty of
      14             :   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
      15             :   GNU Library General Public License for more details.
      16             : 
      17             :   You should have received a copy of the GNU Library General Public License
      18             :   along with GPGME++; see the file COPYING.LIB.  If not, write to the
      19             :   Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
      20             :   Boston, MA 02110-1301, USA.
      21             : */
      22             : 
      23             : // -*- c++ -*-
      24             : #ifndef __GPGMEPP_KEY_H__
      25             : #define __GPGMEPP_KEY_H__
      26             : 
      27             : #include "global.h"
      28             : #include "notation.h"
      29             : 
      30             : #include "gpgmefw.h"
      31             : 
      32             : #include <memory>
      33             : #include <sys/time.h>
      34             : 
      35             : #include <vector>
      36             : #include <algorithm>
      37             : #include <string>
      38             : 
      39             : namespace GpgME
      40             : {
      41             : 
      42             : class Context;
      43             : 
      44             : class Subkey;
      45             : class UserID;
      46             : class TofuInfo;
      47             : 
      48             : typedef std::shared_ptr< std::remove_pointer<gpgme_key_t>::type > shared_gpgme_key_t;
      49             : 
      50             : //
      51             : // class Key
      52             : //
      53             : 
      54         412 : class GPGMEPP_EXPORT Key
      55             : {
      56             :     friend class ::GpgME::Context;
      57             :     struct Null {
      58           8 :                 Null() {}
      59             :         };
      60             : public:
      61             :     Key();
      62             :     /* implicit */ Key(const Null &);
      63             :     Key(const shared_gpgme_key_t &key);
      64             :     Key(gpgme_key_t key, bool acquireRef);
      65             : 
      66             :     static const Null null;
      67             : 
      68          13 :     const Key &operator=(Key other)
      69             :     {
      70          13 :         swap(other);
      71          13 :         return *this;
      72             :     }
      73             : 
      74             :     const Key &mergeWith(const Key &other);
      75             : 
      76          20 :     void swap(Key &other)
      77             :     {
      78             :         using std::swap;
      79          20 :         swap(this->key, other.key);
      80          20 :     }
      81             : 
      82          34 :     bool isNull() const
      83             :     {
      84          34 :         return !key;
      85             :     }
      86             : 
      87             :     UserID userID(unsigned int index) const;
      88             :     Subkey subkey(unsigned int index) const;
      89             : 
      90             :     unsigned int numUserIDs() const;
      91             :     unsigned int numSubkeys() const;
      92             : 
      93             :     std::vector<UserID> userIDs() const;
      94             :     std::vector<Subkey> subkeys() const;
      95             : 
      96             :     bool isRevoked() const;
      97             :     bool isExpired() const;
      98             :     bool isDisabled() const;
      99             :     bool isInvalid() const;
     100             : 
     101             :     /*! Shorthand for isNull || isRevoked || isExpired ||
     102             :      *                          isDisabled || isInvalid */
     103             :     bool isBad() const;
     104             : 
     105             :     bool canEncrypt() const;
     106             :     /*!
     107             :       This function contains a workaround for old gpgme's: all secret
     108             :       OpenPGP keys canSign() == true, which canReallySign() doesn't
     109             :       have. I don't have time to find what breaks when I remove this
     110             :       workaround, but since Kleopatra merges secret into public keys,
     111             :       the workaround is not necessary there (and actively harms), I've
     112             :       added a new function instead.
     113             :      */
     114             :     bool canSign() const;
     115             :     bool canReallySign() const;
     116             :     bool canCertify() const;
     117             :     bool canAuthenticate() const;
     118             :     bool isQualified() const;
     119             :     bool isDeVs() const;
     120             : 
     121             :     bool hasSecret() const;
     122             :     GPGMEPP_DEPRECATED bool isSecret() const
     123             :     {
     124             :         return hasSecret();
     125             :     }
     126             : 
     127             :     /*!
     128             :       @return true if this is a X.509 root certificate (currently
     129             :       equivalent to something like
     130             :       strcmp( chainID(), subkey(0).fingerprint() ) == 0 )
     131             :     */
     132             :     bool isRoot() const;
     133             : 
     134             :     enum OwnerTrust { Unknown = 0, Undefined = 1, Never = 2,
     135             :                       Marginal = 3, Full = 4, Ultimate = 5
     136             :                     };
     137             : 
     138             :     OwnerTrust ownerTrust() const;
     139             :     char ownerTrustAsString() const;
     140             : 
     141             :     Protocol protocol() const;
     142             :     const char *protocolAsString() const;
     143             : 
     144             :     const char *issuerSerial() const;
     145             :     const char *issuerName() const;
     146             :     const char *chainID() const;
     147             : 
     148             :     const char *keyID() const;
     149             :     const char *shortKeyID() const;
     150             :     const char *primaryFingerprint() const;
     151             : 
     152             :     unsigned int keyListMode() const;
     153             : 
     154             :     /*! Update information about this key.
     155             :      * Starts a keylisting for this key with validity
     156             :      * and tofu information gathering. Blocks for
     157             :      * how long the keylisting takes.*/
     158             :     void update();
     159             : 
     160             :     /**
     161             :      * @brief Add a user id to this key.
     162             :      *
     163             :      * Needs gnupg 2.1.13 and the key needs to be updated
     164             :      * afterwards to see the new uid.
     165             :      *
     166             :      * @param uid should be fully formatted and UTF-8 encoded.
     167             :      *
     168             :      * @returns a possible error.
     169             :      **/
     170             :     Error addUid(const char *uid);
     171             : 
     172             :     /**
     173             :      * @brief try to locate the best pgp key for a given mailbox.
     174             :      *
     175             :      * Boils down to gpg --locate-key <mbox>
     176             :      * This may take some time if remote sources are also
     177             :      * used.
     178             :      *
     179             :      * @param mbox should be a mail address does not need to be normalized.
     180             :      *
     181             :      * @returns The best key for a mailbox or a null key.
     182             :      */
     183             :     static Key locate(const char *mbox);
     184             : 
     185             :     /* @enum Origin
     186             :      * @brief The Origin of the key. */
     187             :     enum Origin : unsigned int {
     188             :         OriginUnknown = 0,
     189             :         OriginKS = 1,
     190             :         OriginDane = 3,
     191             :         OriginWKD = 4,
     192             :         OriginURL = 5,
     193             :         OriginFile = 6,
     194             :         OriginSelf = 7,
     195             :         OriginOther = 31,
     196             :     };
     197             :     /*! Get the origin of the key.
     198             :      *
     199             :      * @returns the Origin. */
     200             :     Origin origin() const;
     201             : 
     202             :     /*! Get the last update time.
     203             :      *
     204             :      * @returns the last update time. */
     205             :     time_t lastUpdate() const;
     206             : private:
     207          41 :     gpgme_key_t impl() const
     208             :     {
     209          41 :         return key.get();
     210             :     }
     211             :     shared_gpgme_key_t key;
     212             : };
     213             : 
     214             : //
     215             : // class Subkey
     216             : //
     217             : 
     218          28 : class GPGMEPP_EXPORT Subkey
     219             : {
     220             : public:
     221             :     Subkey();
     222             :     Subkey(const shared_gpgme_key_t &key, gpgme_sub_key_t subkey);
     223             :     Subkey(const shared_gpgme_key_t &key, unsigned int idx);
     224             : 
     225             :     const Subkey &operator=(Subkey other)
     226             :     {
     227             :         swap(other);
     228             :         return *this;
     229             :     }
     230             : 
     231             :     void swap(Subkey &other)
     232             :     {
     233             :         using std::swap;
     234             :         swap(this->key, other.key);
     235             :         swap(this->subkey, other.subkey);
     236             :     }
     237             : 
     238           0 :     bool isNull() const
     239             :     {
     240           0 :         return !key || !subkey;
     241             :     }
     242             : 
     243             :     Key parent() const;
     244             : 
     245             :     const char *keyID() const;
     246             :     const char *fingerprint() const;
     247             : 
     248             :     time_t creationTime() const;
     249             :     time_t expirationTime() const;
     250             :     bool neverExpires() const;
     251             : 
     252             :     bool isRevoked() const;
     253             :     bool isExpired() const;
     254             :     bool isInvalid() const;
     255             :     bool isDisabled() const;
     256             : 
     257             :     /*! Shorthand for isNull || isRevoked || isExpired ||
     258             :      *                          isDisabled || isInvalid */
     259             :     bool isBad() const;
     260             : 
     261             :     bool canEncrypt() const;
     262             :     bool canSign() const;
     263             :     bool canCertify() const;
     264             :     bool canAuthenticate() const;
     265             :     bool isQualified() const;
     266             :     bool isDeVs() const;
     267             :     bool isCardKey() const;
     268             : 
     269             :     bool isSecret() const;
     270             : 
     271             :     /** Same as gpgme_pubkey_algo_t */
     272             :     enum PubkeyAlgo {
     273             :         AlgoUnknown = 0,
     274             :         AlgoRSA     = 1,
     275             :         AlgoRSA_E   = 2,
     276             :         AlgoRSA_S   = 3,
     277             :         AlgoELG_E   = 16,
     278             :         AlgoDSA     = 17,
     279             :         AlgoECC     = 18,
     280             :         AlgoELG     = 20,
     281             :         AlgoECDSA   = 301,
     282             :         AlgoECDH    = 302,
     283             :         AlgoEDDSA   = 303,
     284             :         AlgoMax     = 1 << 31
     285             :     };
     286             : 
     287             :     PubkeyAlgo publicKeyAlgorithm() const;
     288             : 
     289             :     /**
     290             :       @brief Get the public key algorithm name.
     291             : 
     292             :       This only works for the pre 2.1 algorithms for ECC NULL is returned.
     293             : 
     294             :       @returns a statically allocated string with the name of the public
     295             :                key algorithm, or NULL if that name is not known.
     296             :     */
     297             :     const char *publicKeyAlgorithmAsString() const;
     298             : 
     299             :     /** @brief Same as publicKeyAlgorithmAsString but static. */
     300             :     static const char *publicKeyAlgorithmAsString(PubkeyAlgo algo);
     301             : 
     302             :     /**
     303             :        @brief Get the key algo string like GnuPG 2.1 prints it.
     304             : 
     305             :        This returns combinations of size and algorithm. Like
     306             :        bp512 or rsa2048. Misnamed because publicKeyAlgorithmAsString
     307             :        already used the older pubkey_algo_name.
     308             :        Actually uses gpgme_pubkey_algo_string.
     309             : 
     310             :        @returns the key algorithm as string. Empty string on error.
     311             :     */
     312             :     std::string algoName() const;
     313             : 
     314             :     unsigned int length() const;
     315             : 
     316             :     const char *cardSerialNumber() const;
     317             : 
     318             :     const char *keyGrip() const;
     319             : 
     320             : private:
     321             :     shared_gpgme_key_t key;
     322             :     gpgme_sub_key_t subkey;
     323             : };
     324             : 
     325             : //
     326             : // class UserID
     327             : //
     328             : 
     329          86 : class GPGMEPP_EXPORT UserID
     330             : {
     331             : public:
     332             :     class Signature;
     333             : 
     334             :     UserID();
     335             :     UserID(const shared_gpgme_key_t &key, gpgme_user_id_t uid);
     336             :     UserID(const shared_gpgme_key_t &key, unsigned int idx);
     337             : 
     338           0 :     const UserID &operator=(UserID other)
     339             :     {
     340           0 :         swap(other);
     341           0 :         return *this;
     342             :     }
     343             : 
     344           0 :     void swap(UserID &other)
     345             :     {
     346             :         using std::swap;
     347           0 :         swap(this->key, other.key);
     348           0 :         swap(this->uid, other.uid);
     349           0 :     }
     350             : 
     351           0 :     bool isNull() const
     352             :     {
     353           0 :         return !key || !uid;
     354             :     }
     355             : 
     356             :     Key parent() const;
     357             : 
     358             :     unsigned int numSignatures() const;
     359             :     Signature signature(unsigned int index) const;
     360             :     std::vector<Signature> signatures() const;
     361             : 
     362             :     const char *id() const;
     363             :     const char *name() const;
     364             :     const char *email() const;
     365             :     const char *comment() const;
     366             : 
     367             :     enum Validity { Unknown = 0, Undefined = 1, Never = 2,
     368             :                     Marginal = 3, Full = 4, Ultimate = 5
     369             :                   };
     370             : 
     371             :     Validity validity() const;
     372             :     char validityAsString() const;
     373             : 
     374             :     bool isRevoked() const;
     375             :     bool isInvalid() const;
     376             : 
     377             :     /*! Shorthand for isNull || isRevoked || isInvalid */
     378             :     bool isBad() const;
     379             : 
     380             :     /** TOFU info for this userid.
     381             :      * @returns The TOFU stats or a null TofuInfo.
     382             :      */
     383             :     GpgME::TofuInfo tofuInfo() const;
     384             : 
     385             :     /*! Wrapper around gpgme_addrspec_from_uid.
     386             :      *
     387             :      * The input string should match the format of
     388             :      * a user id string.
     389             :      *
     390             :      * @returns a normalized mail address if found
     391             :      * or an empty string. */
     392             :     static std::string addrSpecFromString(const char *uid);
     393             : 
     394             :     /*! Wrapper around gpgme_addrspec_from_uid.
     395             :      *
     396             :      * @returns a normalized mail address for this userid
     397             :      * or an empty string. */
     398             :     std::string addrSpec() const;
     399             : 
     400             :     /*! Revoke the user id.
     401             :      *
     402             :      * Key needs update afterwards.
     403             :      *
     404             :      * @returns an error on error.*/
     405             :     Error revoke();
     406             : 
     407             :     /*! Get the origin of the key.
     408             :      *
     409             :      * @returns the Origin. */
     410             :     Key::Origin origin() const;
     411             : 
     412             :     /*! Get the last update time.
     413             :      *
     414             :      * @returns the last update time. */
     415             :     time_t lastUpdate() const;
     416             : private:
     417             :     shared_gpgme_key_t key;
     418             :     gpgme_user_id_t uid;
     419             : };
     420             : 
     421             : //
     422             : // class UserID::Signature
     423             : //
     424             : 
     425           0 : class GPGMEPP_EXPORT UserID::Signature
     426             : {
     427             : public:
     428             :     typedef GPGMEPP_DEPRECATED GpgME::Notation Notation;
     429             : 
     430             :     Signature();
     431             :     Signature(const shared_gpgme_key_t &key, gpgme_user_id_t uid, gpgme_key_sig_t sig);
     432             :     Signature(const shared_gpgme_key_t &key, gpgme_user_id_t uid, unsigned int idx);
     433             : 
     434             :     const Signature &operator=(Signature other)
     435             :     {
     436             :         swap(other);
     437             :         return *this;
     438             :     }
     439             : 
     440             :     void swap(Signature &other)
     441             :     {
     442             :         using std::swap;
     443             :         swap(this->key, other.key);
     444             :         swap(this->uid, other.uid);
     445             :         swap(this->sig, other.sig);
     446             :     }
     447             : 
     448           0 :     bool isNull() const
     449             :     {
     450           0 :         return !sig || !uid || !key ;
     451             :     }
     452             : 
     453             :     UserID parent() const;
     454             : 
     455             :     const char *signerKeyID() const;
     456             : 
     457             :     const char *algorithmAsString() const;
     458             :     unsigned int algorithm() const;
     459             :     time_t creationTime() const;
     460             :     time_t expirationTime() const;
     461             :     bool neverExpires() const;
     462             : 
     463             :     bool isRevokation() const;
     464             :     bool isInvalid() const;
     465             :     bool isExpired() const;
     466             :     bool isExportable() const;
     467             : 
     468             :     /*! Shorthand for isNull || isExpired || isInvalid */
     469             :     bool isBad() const;
     470             : 
     471             :     const char *signerUserID() const;
     472             :     const char *signerName() const;
     473             :     const char *signerEmail() const;
     474             :     const char *signerComment() const;
     475             : 
     476             :     unsigned int certClass() const;
     477             : 
     478             :     enum Status { NoError = 0, SigExpired, KeyExpired,
     479             :                   BadSignature, NoPublicKey, GeneralError
     480             :                 };
     481             :     Status status() const;
     482             :     std::string statusAsString() const;
     483             : 
     484             :     const char *policyURL() const;
     485             : 
     486             :     unsigned int numNotations() const;
     487             :     GpgME::Notation notation(unsigned int idx) const;
     488             :     std::vector<GpgME::Notation> notations() const;
     489             : 
     490             : private:
     491             :     shared_gpgme_key_t key;
     492             :     gpgme_user_id_t uid;
     493             :     gpgme_key_sig_t sig;
     494             : };
     495             : 
     496             : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, const UserID &uid);
     497             : GPGMEPP_EXPORT std::ostream &operator<<(std::ostream &os, const Key &key);
     498             : 
     499             : } // namespace GpgME
     500             : 
     501           0 : GPGMEPP_MAKE_STD_SWAP_SPECIALIZATION(Key)
     502             : GPGMEPP_MAKE_STD_SWAP_SPECIALIZATION(Subkey)
     503             : GPGMEPP_MAKE_STD_SWAP_SPECIALIZATION(UserID)
     504             : GPGMEPP_MAKE_STD_SWAP_SPECIALIZATION(UserID::Signature)
     505             : 
     506           0 : GPGMEPP_MAKE_STRCMP(ByFingerprint, .primaryFingerprint());
     507             : GPGMEPP_MAKE_STRCMP(ByKeyID, .keyID());
     508             : GPGMEPP_MAKE_STRCMP(ByShortKeyID, .shortKeyID());
     509             : GPGMEPP_MAKE_STRCMP(ByChainID, .chainID());
     510             : 
     511             : #endif // __GPGMEPP_KEY_H__

Generated by: LCOV version 1.13