diff --git a/src/mnemonics/electrum-words.cpp b/src/mnemonics/electrum-words.cpp index 897ab34e..718bbfd9 100644 --- a/src/mnemonics/electrum-words.cpp +++ b/src/mnemonics/electrum-words.cpp @@ -26,7 +26,11 @@ // STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF // THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -/* +/*! + * \file electrum-words.cpp + * + * \brief Mnemonic seed generation and wallet restoration from them. + * * This file and its header file are for translating Electrum-style word lists * into their equivalent byte representations for cross-compatibility with * that method of "backing up" one's wallet keys. @@ -56,11 +60,20 @@ namespace const std::string LANGUAGES_DIRECTORY = "languages"; const std::string OLD_WORD_FILE = "old-word-list"; + /*! + * Tells if the module hasn't been initialized with a word list file. + * \return Whether the module hasn't been initialized with a word list file. + */ bool is_uninitialized() { return num_words == 0 ? true : false; } + /*! + * Create word list map and array data structres for use during inter-conversion between + * words and secret key. + * \param word_file Path to the word list file from pwd. + */ void create_data_structures(const std::string &word_file) { words_array.clear(); @@ -82,6 +95,11 @@ namespace input_stream.close(); } + /*! + * Tells if all the words passed in wlist was present in current word list file. + * \param wlist List of words to match. + * \return Whether they were all present or not. + */ bool word_list_file_match(const std::vector &wlist) { for (std::vector::const_iterator it = wlist.begin(); it != wlist.end(); it++) @@ -95,15 +113,28 @@ namespace } } +/*! + * \namespace crypto + */ namespace crypto { + /*! + * \namespace ElectrumWords + * + * \brief Mnemonic seed word generation and wallet restoration. + */ namespace ElectrumWords { - + /*! + * \brief Called to initialize it work with a word list file. + * \param language Language of the word list file. + * \param old_word_list Whether it is to use the old style word list file. + */ void init(const std::string &language, bool old_word_list) { if (old_word_list) { + // Use the old word list file if told to. create_data_structures(WORD_LISTS_DIRECTORY + '/' + OLD_WORD_FILE); is_old_style_mnemonics = true; } @@ -119,6 +150,10 @@ namespace crypto } } + /*! + * \brief If the module is currenly using an old style word list. + * \return Whether it is currenly using an old style word list. + */ bool get_is_old_style_mnemonics() { if (is_uninitialized()) @@ -127,12 +162,12 @@ namespace crypto } return is_old_style_mnemonics; } - /* convert words to bytes, 3 words -> 4 bytes - * returns: - * false if not a multiple of 3 words, or if a words is not in the - * words list - * - * true otherwise + + /*! + * \brief Converts seed words to bytes (secret key). + * \param words String containing the words separated by spaces. + * \param dst To put the secret key restored from the words. + * \return false if not a multiple of 3 words, or if word is not in the words list */ bool words_to_bytes(const std::string& words, crypto::secret_key& dst) { @@ -143,6 +178,7 @@ namespace crypto std::vector languages; get_language_list(languages); + // Try to find a word list file that contains all the words in the word list. std::vector::iterator it; for (it = languages.begin(); it != languages.end(); it++) { @@ -152,6 +188,7 @@ namespace crypto break; } } + // If no such file was found, see if the old style word list file has them all. if (it == languages.end()) { init("", true); @@ -192,10 +229,11 @@ namespace crypto return true; } - /* convert bytes to words, 4 bytes-> 3 words - * returns: - * false if wrong number of bytes (shouldn't be possible) - * true otherwise + /*! + * \brief Converts bytes (secret key) to seed words. + * \param src Secret key + * \param words Space separated words get copied here. + * \return Whether it was successful or not. Unsuccessful if wrong key size. */ bool bytes_to_words(const crypto::secret_key& src, std::string& words) { @@ -229,6 +267,10 @@ namespace crypto return false; } + /*! + * \brief Gets a list of seed languages that are supported. + * \param languages The list gets added to this. + */ void get_language_list(std::vector &languages) { languages.clear(); @@ -245,6 +287,6 @@ namespace crypto } } - } // namespace ElectrumWords + } -} // namespace crypto +} diff --git a/src/mnemonics/electrum-words.h b/src/mnemonics/electrum-words.h index 73db652d..687ac76c 100644 --- a/src/mnemonics/electrum-words.h +++ b/src/mnemonics/electrum-words.h @@ -26,7 +26,11 @@ // STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF // THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -/* +/*! + * \file electrum-words.h + * + * \brief Mnemonic seed generation and wallet restoration from them. + * * This file and its cpp file are for translating Electrum-style word lists * into their equivalent byte representations for cross-compatibility with * that method of "backing up" one's wallet keys. @@ -37,14 +41,51 @@ #include #include "crypto/crypto.h" // for declaration of crypto::secret_key +/*! + * \namespace crypto + */ namespace crypto { + /*! + * \namespace ElectrumWords + * + * \brief Mnemonic seed word generation and wallet restoration. + */ namespace ElectrumWords { + /*! + * \brief Called to initialize it work with a word list file. + * \param language Language of the word list file. + * \param old_word_list Whether it is to use the old style word list file. + */ void init(const std::string &language, bool old_word_list=false); + + /*! + * \brief Converts seed words to bytes (secret key). + * \param words String containing the words separated by spaces. + * \param dst To put the secret key restored from the words. + * \return false if not a multiple of 3 words, or if word is not in the words list + */ bool words_to_bytes(const std::string& words, crypto::secret_key& dst); + + /*! + * \brief Converts bytes (secret key) to seed words. + * \param src Secret key + * \param words Space separated words get copied here. + * \return Whether it was successful or not. Unsuccessful if wrong key size. + */ bool bytes_to_words(const crypto::secret_key& src, std::string& words); + + /*! + * \brief Gets a list of seed languages that are supported. + * \param languages The list gets added to this. + */ void get_language_list(std::vector &languages); + + /*! + * \brief If the module is currenly using an old style word list. + * \return Whether it is currenly using an old style word list. + */ bool get_is_old_style_mnemonics(); } } diff --git a/src/simplewallet/simplewallet.cpp b/src/simplewallet/simplewallet.cpp index 2ede2f20..9d6f23e6 100644 --- a/src/simplewallet/simplewallet.cpp +++ b/src/simplewallet/simplewallet.cpp @@ -28,6 +28,12 @@ // // Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers +/*! + * \file simplewallet.cpp + * + * \brief Source file that defines simple_wallet class. + */ + #include #include #include @@ -438,6 +444,13 @@ bool simple_wallet::try_connect_to_daemon() return true; } +/*! + * \brief Gets the word seed language from the user. + * + * User is asked to choose from a list of supported languages. + * + * \return The chosen language. + */ std::string simple_wallet::get_mnemonic_language() { std::vector language_list; @@ -498,15 +511,16 @@ bool simple_wallet::new_wallet(const string &wallet_file, const std::string& pas // convert rng value to electrum-style word list std::string electrum_words; + // Ask for language if it is not a wallet restore or if the old version of the wallet + // had given the user an old style word list. if (!m_restore_deterministic_wallet || crypto::ElectrumWords::get_is_old_style_mnemonics()) { if (crypto::ElectrumWords::get_is_old_style_mnemonics()) { + // The user had used an older version of the wallet with old style mnemonics. message_writer(epee::log_space::console_color_green, false) << "\nYou have been using " << "a deprecated word list file. Please use the new seed that we provide.\n"; } - // Ask for language if it is not a wallet restore or if the old version of the wallet - // had given the user an old style word list. std::string mnemonic_language = get_mnemonic_language(); try { diff --git a/src/simplewallet/simplewallet.h b/src/simplewallet/simplewallet.h index 7a21f1cd..8567b234 100644 --- a/src/simplewallet/simplewallet.h +++ b/src/simplewallet/simplewallet.h @@ -28,6 +28,11 @@ // // Parts of this file are originally copyright (c) 2012-2013 The Cryptonote developers +/*! + * \file simplewallet.h + * + * \brief Header file that declares simple_wallet class. + */ #pragma once #include @@ -41,12 +46,15 @@ #include "password_container.h" #include "crypto/crypto.h" // for definition of crypto::secret_key - +/*! + * \namespace cryptonote + * \brief Holds cryptonote related classes and helpers. + */ namespace cryptonote { - /************************************************************************/ - /* */ - /************************************************************************/ + /*! + * \brief Manages wallet operations. This is the most abstracted wallet class. + */ class simple_wallet : public tools::i_wallet2_callback { public: @@ -92,6 +100,14 @@ namespace cryptonote uint64_t get_daemon_blockchain_height(std::string& err); bool try_connect_to_daemon(); bool ask_wallet_create_if_needed(); + + /*! + * \brief Gets the word seed language from the user. + * + * User is asked to choose from a list of supported languages. + * + * \return The chosen language. + */ std::string get_mnemonic_language(); //----------------- i_wallet2_callback ---------------------