OTCachedKey.hpp

Go to the documentation of this file.

/************************************************************
 *
 *  OTCachedKey.hpp
 *
 */

/************************************************************
 -----BEGIN PGP SIGNED MESSAGE-----
 Hash: SHA1

 *                 OPEN TRANSACTIONS
 *
 *       Financial Cryptography and Digital Cash
 *       Library, Protocol, API, Server, CLI, GUI
 *
 *       -- Anonymous Numbered Accounts.
 *       -- Untraceable Digital Cash.
 *       -- Triple-Signed Receipts.
 *       -- Cheques, Vouchers, Transfers, Inboxes.
 *       -- Basket Currencies, Markets, Payment Plans.
 *       -- Signed, XML, Ricardian-style Contracts.
 *       -- Scripted smart contracts.
 *
 *  Copyright (C) 2010-2013 by "Fellow Traveler" (A pseudonym)
 *
 *  EMAIL:
 *  [email protected]
 *
 *  BITCOIN:  1NtTPVVjDsUfDWybS4BwvHpG2pdS9RnYyQ
 *
 *  KEY FINGERPRINT (PGP Key in license file):
 *  9DD5 90EB 9292 4B48 0484  7910 0308 00ED F951 BB8E
 *
 *  OFFICIAL PROJECT WIKI(s):
 *  https://github.com/FellowTraveler/Moneychanger
 *  https://github.com/FellowTraveler/Open-Transactions/wiki
 *
 *  WEBSITE:
 *  http://www.OpenTransactions.org/
 *
 *  Components and licensing:
 *   -- Moneychanger..A Java client GUI.....LICENSE:.....GPLv3
 *   -- otlib.........A class library.......LICENSE:...LAGPLv3
 *   -- otapi.........A client API..........LICENSE:...LAGPLv3
 *   -- opentxs/ot....Command-line client...LICENSE:...LAGPLv3
 *   -- otserver......Server Application....LICENSE:....AGPLv3
 *  Github.com/FellowTraveler/Open-Transactions/wiki/Components
 *
 *  All of the above OT components were designed and written by
 *  Fellow Traveler, with the exception of Moneychanger, which
 *  was contracted out to Vicky C ([email protected]).
 *  The open-source community has since actively contributed.
 *
 *  -----------------------------------------------------
 *
 *   LICENSE:
 *   This program is free software: you can redistribute it
 *   and/or modify it under the terms of the GNU Affero
 *   General Public License as published by the Free Software
 *   Foundation, either version 3 of the License, or (at your
 *   option) any later version.
 *
 *   ADDITIONAL PERMISSION under the GNU Affero GPL version 3
 *   section 7: (This paragraph applies only to the LAGPLv3
 *   components listed above.) If you modify this Program, or
 *   any covered work, by linking or combining it with other
 *   code, such other code is not for that reason alone subject
 *   to any of the requirements of the GNU Affero GPL version 3.
 *   (==> This means if you are only using the OT API, then you
 *   don't have to open-source your code--only your changes to
 *   Open-Transactions itself must be open source. Similar to
 *   LGPLv3, except it applies to software-as-a-service, not
 *   just to distributing binaries.)
 *
 *   Extra WAIVER for OpenSSL, Lucre, and all other libraries
 *   used by Open Transactions: This program is released under
 *   the AGPL with the additional exemption that compiling,
 *   linking, and/or using OpenSSL is allowed. The same is true
 *   for any other open source libraries included in this
 *   project: complete waiver from the AGPL is hereby granted to
 *   compile, link, and/or use them with Open-Transactions,
 *   according to their own terms, as long as the rest of the
 *   Open-Transactions terms remain respected, with regard to
 *   the Open-Transactions code itself.
 *
 *   Lucre License:
 *   This code is also "dual-license", meaning that Ben Lau-
 *   rie's license must also be included and respected, since
 *   the code for Lucre is also included with Open Transactions.
 *   See Open-Transactions/src/otlib/lucre/LUCRE_LICENSE.txt
 *   The Laurie requirements are light, but if there is any
 *   problem with his license, simply remove the Lucre code.
 *   Although there are no other blind token algorithms in Open
 *   Transactions (yet. credlib is coming), the other functions
 *   will continue to operate.
 *   See Lucre on Github:  https://github.com/benlaurie/lucre
 *   -----------------------------------------------------
 *   You should have received a copy of the GNU Affero General
 *   Public License along with this program.  If not, see:
 *   http://www.gnu.org/licenses/
 *
 *   If you would like to use this software outside of the free
 *   software license, please contact FellowTraveler.
 *   (Unfortunately many will run anonymously and untraceably,
 *   so who could really stop them?)
 *
 *   DISCLAIMER:
 *   This program is distributed in the hope that it will be
 *   useful, but WITHOUT ANY WARRANTY; without even the implied
 *   warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 *   PURPOSE.  See the GNU Affero General Public License for
 *   more details.

 -----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1.4.9 (Darwin)

 iQIcBAEBAgAGBQJRSsfJAAoJEAMIAO35UbuOQT8P/RJbka8etf7wbxdHQNAY+2cC
 vDf8J3X8VI+pwMqv6wgTVy17venMZJa4I4ikXD/MRyWV1XbTG0mBXk/7AZk7Rexk
 KTvL/U1kWiez6+8XXLye+k2JNM6v7eej8xMrqEcO0ZArh/DsLoIn1y8p8qjBI7+m
 aE7lhstDiD0z8mwRRLKFLN2IH5rAFaZZUvj5ERJaoYUKdn4c+RcQVei2YOl4T0FU
 LWND3YLoH8naqJXkaOKEN4UfJINCwxhe5Ke9wyfLWLUO7NamRkWD2T7CJ0xocnD1
 sjAzlVGNgaFDRflfIF4QhBx1Ddl6wwhJfw+d08bjqblSq8aXDkmFA7HeunSFKkdn
 oIEOEgyj+veuOMRJC5pnBJ9vV+7qRdDKQWaCKotynt4sWJDGQ9kWGWm74SsNaduN
 TPMyr9kNmGsfR69Q2Zq/FLcLX/j8ESxU+HYUB4vaARw2xEOu2xwDDv6jt0j3Vqsg
 x7rWv4S/Eh18FDNDkVRChiNoOIilLYLL6c38uMf1pnItBuxP3uhgY6COm59kVaRh
 nyGTYCDYD2TK+fI9o89F1297uDCwEJ62U0Q7iTDp5QuXCoxkPfv8/kX6lS6T3y9G
 M9mqIoLbIQ1EDntFv7/t6fUTS2+46uCrdZWbQ5RjYXdrzjij02nDmJAm2BngnZvd
 kamH0Y/n11lCvo1oQxM+
 =uSzz
 -----END PGP SIGNATURE-----
 **************************************************************/

#ifndef OPENTXS_CORE_CRYPTO_OTCACHEDKEY_HPP
#define OPENTXS_CORE_CRYPTO_OTCACHEDKEY_HPP

#include <string>
#include <memory>
#include <map>
#include <mutex>
#include <thread>

namespace opentxs
{

class OTASCIIArmor;
class OTCachedKey;
class OTIdentifier;
class OTPassword;
class OTString;
class OTSymmetricKey;


// This is only the hard-coded default; it's also configurable in the opt file.
#define OT_MASTER_KEY_TIMEOUT 300

typedef std::map<std::string, std::shared_ptr<OTCachedKey>> mapOfCachedKeys;

class OTCachedKey
{
private:
    std::thread* m_pThread;    // The thread used for destroying the password
                               // after the timeout period.
    int32_t m_nTimeoutSeconds; // The master password will be stored internally
                               // for X seconds, and then destroyed.
    OTPassword* m_pMasterPassword; // Created when password is passed in;
                                   // destroyed by Timer after X seconds.

    bool m_bUse_System_Keyring; // if set to true, then additionally use the
                                // local OS's standard API for
                                // storing/retrieving secrets. (Store the master
                                // key here whenever it's decrypted, and try to
                                // retrieve from here whenever it's needed,
                                // before resorting to asking the user to type
                                // his passphrase.) This is configurable in the
                                // config file.

    OTSymmetricKey* m_pSymmetricKey; // Encrypted form of the master key.
                                     // Serialized by OTWallet or OTServer.
    std::mutex m_Mutex; // Mutex used for serializing access to this
                        // instance.
    bool m_bPaused; // If you want to force the old system, PAUSE the master key
                    // (REMEMBER to Unpause when done!)
    OTCachedKey(int32_t nTimeoutSeconds = OT_MASTER_KEY_TIMEOUT);
    static std::mutex s_mutexThreadTimeout;
    static std::mutex s_mutexCachedKeys;
    static mapOfCachedKeys s_mapCachedKeys; // Now we have many "master keys,"
                                            // mapped by their symmetric key ID.
                                            // These are actually temps, just so
                                            // we can safely cache the
                                            // passphrases for various symmetric
                                            // keys, between uses of that
                                            // symmetric key. Such as Pop'ing
                                            // tokens off of a purse, over and
                                            // over again. Normally in the API,
                                            // this would have to load the key
                                            // each time. By caching here, we
                                            // can exploit all the cool master
                                            // key code, with its security, and
                                            // threads, and timeouts, etc for
                                            // every symmetric key we use. Just
                                            // pass an ID into It() and if it's
                                            // on the map, a pointer will be
    // returned. Pass nullptr into It() (no
    // arguments) to get a pointer to
    // the global Master Key (for Nyms.)
public:
    std::mutex* GetMutex()
    {
        return &m_Mutex;
    } // So static functions using this CachedKey can also lock its mutex.
    EXPORT OTCachedKey(const OTASCIIArmor& ascCachedKey);
    EXPORT ~OTCachedKey();

    // if you pass in a master key ID, it will look it up on an existing cached
    // map of master keys. Otherwise it will use "the" global Master Key
    // (the one used for the Nyms.)
    EXPORT static std::shared_ptr<OTCachedKey> It(
        OTIdentifier* pIdentifier = nullptr);

    // if you pass in a master key, it will look it up on an existing cached map
    // of master keys, based on the ID of the master key passed in. If not
    // there, it copies the one passed in, and returns a pointer to the copy.
    // (Do NOT delete it.)
    EXPORT static std::shared_ptr<OTCachedKey> It(OTCachedKey& theSourceKey);

    EXPORT static void Cleanup(); // Call on application shutdown. Called in
                                  // CleanupOTAPI and also in OTServer wherever
                                  // it cleans up.
    EXPORT bool GetIdentifier(OTIdentifier& theIdentifier) const;
    EXPORT bool GetIdentifier(OTString& strIdentifier) const;
    EXPORT bool IsGenerated();
    EXPORT bool HasHashCheck();
    EXPORT bool IsUsingSystemKeyring() const
    {
        return m_bUse_System_Keyring;
    }
    EXPORT void UseSystemKeyring(bool bUsing = true)
    {
        m_bUse_System_Keyring = bUsing;
    } // Start using system keyring.
    EXPORT bool Pause();
    EXPORT bool Unpause();
    EXPORT bool isPaused();
    EXPORT bool SerializeTo(OTASCIIArmor& ascOutput);
    EXPORT bool SerializeFrom(const OTASCIIArmor& ascInput);

    // These two functions are used by the OTServer or OTWallet that actually
    // keeps
    // the master key. The owner sets the master key pointer on initialization,
    // and then
    // later when the password callback code in OTAsymmetricKey needs to access
    // the master
    // key, it can use GetMasterPassword to access it.
    //
    EXPORT void SetCachedKey(
        const OTASCIIArmor& ascCachedKey); // OTServer/OTWallet calls this, I
                                           // instantiate.

    EXPORT int32_t GetTimeoutSeconds();
    EXPORT void SetTimeoutSeconds(int32_t nTimeoutSeconds); // So we can load
                                                            // from the config
                                                            // file.

    // For Nyms, which have a global master key serving as their "passphrase"
    // (for that wallet),
    // The password callback uses OTCachedKey::It() to get the instance, and
    // then GetMasterPassword
    // to get the passphrase for any individual Nym. Otherwise,
    // OTCachedKey::It(OTSymmetricKey *) looks
    // up a cached master key based on the ID of the key passed in. For example,
    // OTPurse has a symmetric
    // key and master key (optionally, vs using a Nym.) The symmetric key
    // contains the actual key for the
    // tokens, and the master key is used for the passphrase, which may be
    // cached, or may have timed out,
    // and then re-retrieved from the user (either way). The purse, rather than
    // using the global
    // master key to get the passphrase, (which _would_ happen if the purse is
    // encrypted to a nym) will
    // instead use its own internal master key to get its passphrase (also
    // retrieving from the user if
    // necessary.)
    EXPORT bool GetMasterPassword(std::shared_ptr<OTCachedKey>& mySharedPtr,
                                  OTPassword& theOutput,
                                  const char* szDisplay = nullptr,
                                  bool bVerifyTwice = false);
    // Caller must delete!
    EXPORT static std::shared_ptr<OTCachedKey> CreateMasterPassword(
        OTPassword& theOutput, const char* szDisplay = nullptr,
        int32_t nTimeoutSeconds = OT_MASTER_KEY_TIMEOUT);

    EXPORT void DestroyMasterPassword(); // The thread, when the time comes,
                                         // calls this method using the instance
                                         // pointer that was passed into the
                                         // thread originally. The actual
                                         // encrypted version is kept -- only
                                         // the temporary cleartext version is
                                         // destroyed.

    EXPORT void ResetMasterPassword(); // If you actually want to create a new
                                       // key, and a new passphrase, then use
                                       // this to destroy every last vestige of
                                       // the old one. (Which will cause a new
                                       // one to be automatically generated the
                                       // next time OT requests the master key.)
                                       // NOTE: Make SURE you have all your Nyms
                                       // loaded up and unlocked before you call
                                       // this. Then Save them all again so they
                                       // will be properly stored with the new
                                       // master key.

    EXPORT void LowLevelReleaseThread();

    // The cleartext version (m_pMasterPassword) is deleted and set nullptr
    // after a
    // Timer of X seconds. (Timer thread calls this.)
    // The INSTANCE that owns the thread also passes a pointer to ITSELF.
    // (So we can access password, mutex, timeout value, etc.) This function
    // calls DestroyMasterPassword.
    //
    EXPORT static void ThreadTimeout(void* pArg);
};

} // namespace opentxs

#endif // OPENTXS_CORE_CRYPTO_OTCACHEDKEY_HPP