From ef07ba47bc5628ff54a87dcf179fd9ac1cbf643c Mon Sep 17 00:00:00 2001 From: Kris Nuttycombe Date: Thu, 12 May 2022 08:27:51 -0600 Subject: [PATCH 1/7] Revert "redirect and update source documentation" This reverts commit 70ebc0942af257a72060165579b3f4b44ecefb06. --- doc/dnsseed-policy.md | 52 +++++++++++- doc/files.md | 19 +++-- doc/payment-api.md | 178 ++++++++++++++++++++++++++++++++++++++- doc/security-warnings.md | 108 +++++++++++++++++++++++- doc/shield-coinbase.md | 100 +++++++++++++++++++++- doc/tor.md | 147 +++++++++++++++++++++++++++++++- doc/unit-tests.md | 15 +++- doc/wallet-backup.md | 90 +++++++++++++++++++- 8 files changed, 690 insertions(+), 19 deletions(-) diff --git a/doc/dnsseed-policy.md b/doc/dnsseed-policy.md index 54d739a9a..90fead217 100644 --- a/doc/dnsseed-policy.md +++ b/doc/dnsseed-policy.md @@ -1,6 +1,54 @@ Expectations for DNS Seed operators ==================================== -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/dnsseed_policy.html +Zcash attempts to minimize the level of trust in DNS seeds, +but DNS seeds still pose a small amount of risk for the network. +As such, DNS seeds must be run by entities which have some minimum +level of trust within the Zcash community. -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/dnsseed_policy.rst \ No newline at end of file +Other implementations of Zcash software may also use the same +seeds and may be more exposed. In light of this exposure, this +document establishes some basic expectations for operating DNS seeds. + +0. A DNS seed operating organization or person is expected to follow good +host security practices, maintain control of applicable infrastructure, +and not sell or transfer control of the DNS seed. Any hosting services +contracted by the operator are equally expected to uphold these expectations. + +1. The DNS seed results must consist exclusively of fairly selected and +functioning Zcash nodes from the public network to the best of the +operator's understanding and capability. + +2. For the avoidance of doubt, the results may be randomized but must not +single out any group of hosts to receive different results unless due to an +urgent technical necessity and disclosed. + +3. The results may not be served with a DNS TTL of less than one minute. + +4. Any logging of DNS queries should be only that which is necessary +for the operation of the service or urgent health of the Zcash +network and must not be retained longer than necessary nor disclosed +to any third party. + +5. Information gathered as a result of the operators node-spidering +(not from DNS queries) may be freely published or retained, but only +if this data was not made more complete by biasing node connectivity +(a violation of expectation (1)). + +6. Operators are encouraged, but not required, to publicly document the +details of their operating practices. + +7. A reachable email contact address must be published for inquiries +related to the DNS seed operation. + +If these expectations cannot be satisfied the operator should discontinue +providing services and contact the active Zcash development team as well as +creating an issue in the [Zcash repository](https://github.com/zcash/zcash). + +Behavior outside of these expectations may be reasonable in some +situations but should be discussed in public in advance. + +See also +---------- +- [zcash-seeder](https://github.com/zcash/zcash-seeder) is a reference + implementation of a DNS seed. diff --git a/doc/files.md b/doc/files.md index b29865e58..2d3787912 100644 --- a/doc/files.md +++ b/doc/files.md @@ -1,5 +1,14 @@ -# Data Directory Files - -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/files.html - -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/files.rst +* zcash.conf: contains configuration settings for zcashd +* zcashd.pid: stores the process id of zcashd while running +* blocks/blk000??.dat: block data (custom, 128 MiB per file) +* blocks/rev000??.dat; block undo data (custom) +* blocks/index/*; block index (LevelDB) +* chainstate/*; block chain state database (LevelDB) +* database/*: BDB database environment +* db.log: wallet database log file +* debug.log: contains debug information and general logging generated by zcashd +* fee_estimates.dat: stores statistics used to estimate minimum transaction fees and priorities required for confirmation +* peers.dat: peer IP address database (custom format) +* wallet.dat: personal wallet (BDB) with keys and transactions +* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0 +* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0 diff --git a/doc/payment-api.md b/doc/payment-api.md index 786fb6f3c..9ae6c57c9 100644 --- a/doc/payment-api.md +++ b/doc/payment-api.md @@ -1,5 +1,179 @@ # Zcash Payment API -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/payment_api.html +## Overview -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/payment_api.rst \ No newline at end of file +Zcash extends the Bitcoin Core API with new RPC calls to support private Zcash payments. + +Zcash payments make use of two address formats: + +* taddr - an address for transparent funds (just like a Bitcoin address, value stored in UTXOs) +* zaddr - an address for private funds (value stored in objects called notes) + +When transferring funds from one taddr to another taddr, you can use either the existing Bitcoin RPC calls or the new Zcash RPC calls. + +When a transfer involves zaddrs, you must use the new Zcash RPC calls. + + +## Compatibility with Bitcoin Core + +Zcash supports all commands in the Bitcoin Core API (as of version 0.11.2). Where applicable, Zcash will extend commands in a backwards-compatible way to enable additional functionality. + +We do not recommend use of accounts which are now deprecated in Bitcoin Core. Where the account parameter exists in the API, please use “” as its value, otherwise an error will be returned. + +To support multiple users in a single node’s wallet, consider using getnewaddress or z_getnewaddress to obtain a new address for each user. Also consider mapping multiple addresses to each user. + +## List of Zcash API commands + +Optional parameters are denoted in [square brackets]. + +RPC calls by category: + +* Accounting: z_getbalance, z_gettotalbalance +* Addresses : z_getnewaddress, z_listaddresses, z_validateaddress, z_exportviewingkey, z_importviewingkey +* Keys : z_exportkey, z_importkey, z_exportwallet, z_importwallet +* Operation: z_getoperationresult, z_getoperationstatus, z_listoperationids +* Payment : z_listreceivedbyaddress, z_listunspent, z_sendmany, z_shieldcoinbase + +RPC parameter conventions: + +* taddr : Transparent address +* zaddr : Private address +* address : Accepts both private and transparent addresses. +* amount : JSON format decimal number with at most 8 digits of precision, with 1 ZEC expressed as 1.00000000. +* memo : Metadata expressed in hexadecimal format. Limited to 512 bytes, the current size of the memo field of a private transaction. Zero padding is automatic. + +### Accounting + +Command | Parameters | Description +--- | --- | --- +z_getbalance
| address [minconf=1] | Returns the balance of a taddr or zaddr belonging to the node’s wallet.

Optionally set the minimum number of confirmations a private or transparent transaction must have in order to be included in the balance. Use 0 to count unconfirmed transactions. +z_gettotalbalance
| [minconf=1] | Return the total value of funds stored in the node’s wallet.

Optionally set the minimum number of confirmations a private or transparent transaction must have in order to be included in the balance. Use 0 to count unconfirmed transactions.

Output:
{
"transparent" : 1.23,
"private" : 4.56,
"total" : 5.79} + +### Addresses + +Command | Parameters | Description +--- | --- | --- +z_getnewaddress | | Return a new zaddr for sending and receiving payments. The spending key for this zaddr will be added to the node’s wallet.

Output:
zN68D8hSs3... +z_listaddresses | | Returns a list of all the zaddrs in this node’s wallet for which you have a spending key.

Output:
{ [“z123…”, “z456...”, “z789...”] } +z_validateaddress | zaddr | Return information about a given zaddr.

Output:
{"isvalid" : true,
"address" : "zcWsmq...",
"type" : "sprout",
"payingkey" : "f5bb3c...",
"transmissionkey" : "7a58c7...",
"ismine" : true} + +### Key Management + +Command | Parameters | Description +--- | --- | --- +z_exportkey | zaddr | _Requires an unlocked wallet or an unencrypted wallet._

Return a zkey for a given zaddr belonging to the node’s wallet.

The key will be returned as a string formatted using Base58Check as described in the Zcash protocol spec.

Output:AKWUAkypwQjhZ6LLNaMuuuLcmZ6gt5UFyo8m3jGutvALmwZKLdR5 +z_importkey | zkey [rescan=true] | _Wallet must be unlocked._

Add a zkey as returned by z_exportkey to a node's wallet.

The key should be formatted using Base58Check as described in the Zcash protocol spec.

Set rescan to true (the default) to rescan the entire local block database for transactions affecting any address or pubkey script in the wallet (including transactions affecting the newly-added address for this spending key). +z_exportwallet | filename | _Requires an unlocked wallet or an unencrypted wallet._

Creates or overwrites a file with taddr private keys and zaddr private keys in a human-readable format.

Filename is the file in which the wallet dump will be placed. May be prefaced by an absolute file path. An existing file with that name will be overwritten.

No value is returned but a JSON-RPC error will be reported if a failure occurred. +z_importwallet | filename | _Requires an unlocked wallet or an unencrypted wallet._

Imports private keys from a file in wallet export file format (see z_exportwallet). These keys will be added to the keys currently in the wallet. This call may need to rescan all or parts of the block chain for transactions affecting the newly-added keys, which may take several minutes.

Filename is the file to import. The path is relative to zcashd’s working directory.

No value is returned but a JSON-RPC error will be reported if a failure occurred. +z_exportviewingkey | zaddr | Reveals the viewing key corresponding to 'zaddr'. Then the z_importviewingkey can be used with this output. +z_importviewingkey | vkey [rescan=whenkeyisnew] [startHeight=0] | Adds a viewing key (as returned by z_exportviewingkey) to your wallet. + + +### Payment + +Command | Parameters | Description +--- | --- | --- +z_listreceivedbyaddress
| zaddr [minconf=1] | Return a list of amounts received by a zaddr belonging to the node’s wallet.

Optionally set the minimum number of confirmations which a received amount must have in order to be included in the result. Use 0 to count unconfirmed transactions.

Output:
[{
“txid”: “4a0f…”,
“amount”: 0.54,
“memo”:”F0FF…”,}, {...}, {...}
] +z_listunspent | [minconf=1] [maxconf=9999999] [includeWatchonly=false] [zaddrs] | Returns array of unspent shielded notes with between minconf and maxconf (inclusive) confirmations.

Optionally filter to only include notes sent to specified addresses.

When minconf is 0, unspent notes with zero confirmations are returned, even though they are not immediately spendable.

Results are an array of Objects, each of which has: {txid, jsindex, jsoutindex, confirmations, address, amount, memo} +z_sendmany
| fromaddress amounts [minconf=1] [fee=0.0001] | _This is an Asynchronous RPC call_

Send funds from an address to multiple outputs. The address can be either a taddr or a zaddr.

Amounts is a list containing key/value pairs corresponding to the addresses and amount to pay. Each output address can be in taddr or zaddr format.

When sending to a zaddr, you also have the option of attaching a memo in hexadecimal format.

**NOTE:**When sending coinbase funds to a zaddr, the node's wallet does not allow any change. Put another way, spending a partial amount of a coinbase utxo is not allowed. This is not a consensus rule but a local wallet rule due to the current implementation of z_sendmany. In future, this rule may be removed.

Example of Outputs parameter:
[{“address”:”t123…”, “amount”:0.005},
,{“address”:”z010…”,”amount”:0.03, “memo”:”f508af…”}]

Optionally set the minimum number of confirmations which a private or transparent transaction must have in order to be used as an input. When sending from a zaddr, minconf must be greater than zero.

Optionally set a transaction fee, which by default is 0.0001 ZEC.

Any transparent change will be sent to a new transparent address. Any private change will be sent back to the zaddr being used as the source of funds.

Returns an operationid. You use the operationid value with z_getoperationstatus and z_getoperationresult to obtain the result of sending funds, which if successful, will be a txid. +z_shieldcoinbase
| fromaddress toaddress [fee=0.0001] [limit=50] | _This is an Asynchronous RPC call_

Shield transparent coinbase funds by sending to a shielded z address. Utxos selected for shielding will be locked. If there is an error, they are unlocked. The RPC call `listlockunspent` can be used to return a list of locked utxos.

The number of coinbase utxos selected for shielding can be set with the limit parameter, which has a default value of 50. If the parameter is set to 0, the number of utxos selected is limited by the `-mempooltxinputlimit` option. Any limit is constrained by a consensus rule defining a maximum transaction size of 100000 bytes.

The from address is a taddr or "*" for all taddrs belonging to the wallet. The to address is a zaddr. The default fee is 0.0001.

Returns an object containing an operationid which can be used with z_getoperationstatus and z_getoperationresult, along with key-value pairs regarding how many utxos are being shielded in this transaction and what remains to be shielded. + +### Operations + +Asynchronous calls return an OperationStatus object which is a JSON object with the following defined key-value pairs: + +* operationid : unique identifier for the async operation. Use this value with z_getoperationstatus or z_getoperationresult to poll and query the operation and obtain its result. +* status : current status of operation + * queued : operation is pending execution + * executing : operation is currently being executed + * cancelled + * failed. + * success +* result : result object if the status is ‘success’. The exact form of the result object is dependent on the call itself. +* error: error object if the status is ‘failed’. The error object has the following key-value pairs: + * code : number + * message: error message + +Depending on the type of asynchronous call, there may be other key-value pairs. For example, a z_sendmany operation will also include the following in an OperationStatus object: + +* method : name of operation e.g. z_sendmany +* params : an object containing the parameters to z_sendmany + +Currently, as soon as you retrieve the operation status for an operation which has finished, that is it has either succeeded, failed, or been cancelled, the operation and any associated information is removed. + +It is currently not possible to cancel operations. + +Command | Parameters | Description +--- | --- | --- +z_getoperationresult
| [operationids] | Return OperationStatus JSON objects for all completed operations the node is currently aware of, and then remove the operation from memory.

Operationids is an optional array to filter which operations you want to receive status objects for.

Output is a list of operation status objects, where the status is either "failed", "cancelled" or "success".
[
{“operationid”: “opid-11ee…”,
“status”: “cancelled”},
{“operationid”: “opid-9876”, “status”: ”failed”},
{“operationid”: “opid-0e0e”,
“status”:”success”,
“execution_time”:”25”,
“result”: {“txid”:”af3887654…”,...}
},
]

Examples:
zcash-cli z_getoperationresult '["opid-8120fa20-5ee7-4587-957b-f2579c2d882b"]'
zcash-cli z_getoperationresult +z_getoperationstatus
| [operationids] | Return OperationStatus JSON objects for all operations the node is currently aware of.

Operationids is an optional array to filter which operations you want to receive status objects for.

Output is a list of operation status objects.
[
{“operationid”: “opid-12ee…”,
“status”: “queued”},
{“operationid”: “opd-098a…”, “status”: ”executing”},
{“operationid”: “opid-9876”, “status”: ”failed”}
]

When the operation succeeds, the status object will also include the result.

{“operationid”: “opid-0e0e”,
“status”:”success”,
“execution_time”:”25”,
“result”: {“txid”:”af3887654…”,...}
} +z_listoperationids
| [state] | Return a list of operationids for all operations which the node is currently aware of.

State is an optional string parameter to filter the operations you want listed by their state. Acceptable parameter values are ‘queued’, ‘executing’, ‘success’, ‘failed’, ‘cancelled’.

[“opid-0e0e…”, “opid-1af4…”, … ] + +## Asynchronous RPC call Error Codes + +Zcash error codes are defined in https://github.com/zcash/zcash/blob/master/src/rpcprotocol.h + +### z_sendmany error codes + +RPC_INVALID_PARAMETER (-8) | _Invalid, missing or duplicate parameter_ +---------------------------| ------------------------------------------------- +"Minconf cannot be zero when sending from zaddr" | Cannot accept minimum confirmation value of zero when sending from zaddr. +"Minconf cannot be negative" | Cannot accept negative minimum confirmation number. +"Minimum number of confirmations cannot be less than 0" | Cannot accept negative minimum confirmation number. +"From address parameter missing" | Missing an address to send funds from. +"No recipients" | Missing recipient addresses. +"Memo must be in hexadecimal format" | Encrypted memo field data must be in hexadecimal format. +"Memo size of __ is too big, maximum allowed is __ " | Encrypted memo field data exceeds maximum size of 512 bytes. +"From address does not belong to this node, zaddr spending key not found." | Sender address spending key not found. +"Invalid parameter, expected object" | Expected object. +"Invalid parameter, unknown key: __" | Unknown key. +"Invalid parameter, expected valid size" | Invalid size. +"Invalid parameter, expected hex txid" | Invalid txid. +"Invalid parameter, vout must be positive" | Invalid vout. +"Invalid parameter, duplicated address" | Address is duplicated. +"Invalid parameter, amounts array is empty" | Amounts array is empty. +"Invalid parameter, unknown key" | Key not found. +"Invalid parameter, unknown address format" | Unknown address format. +"Invalid parameter, size of memo" | Invalid memo field size. +"Invalid parameter, amount must be positive" | Invalid or negative amount. +"Invalid parameter, too many zaddr outputs" | z_address outputs exceed maximum allowed. +"Invalid parameter, expected memo data in hexadecimal format" | Encrypted memo field is not in hexadecimal format. +"Invalid parameter, size of memo is larger than maximum allowed __ " | Encrypted memo field data exceeds maximum size of 512 bytes. + + +RPC_INVALID_ADDRESS_OR_KEY (-5) | _Invalid address or key_ +--------------------------------| --------------------------- +"Invalid from address, no spending key found for zaddr" | z_address spending key not found. +"Invalid output address, not a valid taddr." | Transparent output address is invalid. +"Invalid from address, should be a taddr or zaddr." | Sender address is invalid. +"From address does not belong to this node, zaddr spending key not found." | Sender address spending key not found. + + +RPC_WALLET_INSUFFICIENT_FUNDS (-6) | _Not enough funds in wallet or account_ +-----------------------------------| ------------------------------------------ +"Insufficient funds, no UTXOs found for taddr from address." | Insufficient funds for sending address. +"Could not find any non-coinbase UTXOs to spend. Coinbase UTXOs can only be sent to a single zaddr recipient." | Must send Coinbase UTXO to a single z_address. +"Could not find any non-coinbase UTXOs to spend." | No available non-coinbase UTXOs. +"Insufficient funds, no unspent notes found for zaddr from address." | Insufficient funds for sending address. +"Insufficient transparent funds, have __, need __ plus fee __" | Insufficient funds from transparent address. +"Insufficient protected funds, have __, need __ plus fee __" | Insufficient funds from shielded address. + +RPC_WALLET_ERROR (-4) | _Unspecified problem with wallet_ +----------------------| ------------------------------------- +"Could not find previous JoinSplit anchor" | Try restarting node with `-reindex`. +"Error decrypting output note of previous JoinSplit: __" | +"Could not find witness for note commitment" | Try restarting node with `-rescan`. +"Witness for note commitment is null" | Missing witness for note commitment. +"Witness for spendable note does not have same anchor as change input" | Invalid anchor for spendable note witness. +"Not enough funds to pay miners fee" | Retry with sufficient funds. +"Missing hex data for raw transaction" | Raw transaction data is null. +"Missing hex data for signed transaction" | Hex value for signed transaction is null. +"Send raw transaction did not return an error or a txid." | + +RPC_WALLET_ENCRYPTION_FAILED (-16) | _Failed to encrypt the wallet_ +-------------------------------------------------------------------------| ------------------------------------- +"Failed to sign transaction" | Transaction was not signed, sign transaction and retry. + +RPC_WALLET_KEYPOOL_RAN_OUT (-12) | _Keypool ran out, call keypoolrefill first_ +-------------------------------------------------------------------------| ----------------------------------------------- +"Could not generate a taddr to use as a change address" | Call keypoolrefill and retry. diff --git a/doc/security-warnings.md b/doc/security-warnings.md index 53da5206e..556a55c4a 100644 --- a/doc/security-warnings.md +++ b/doc/security-warnings.md @@ -1,6 +1,110 @@ Security Warnings ==================== -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/security_warnings.html +Security Audit +-------------- -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/security_warnings.rst \ No newline at end of file +Zcash has been subjected to a formal third-party security review. For security +announcements, audit results and other general security information, see +https://z.cash/support/security.html + +x86-64 Linux Only +----------------------- + +There are [known bugs](https://github.com/scipr-lab/libsnark/issues/26) which +make proving keys generated on 64-bit systems unusable on 32-bit and big-endian +systems. It's unclear if a warning will be issued in this case, or if the +proving system will be silently compromised. + +Wallet Encryption +----------------- + +Wallet encryption is disabled, for several reasons: + +- Encrypted wallets are unable to correctly detect shielded spends (due to the + nature of unlinkability of JoinSplits) and can incorrectly show larger + available shielded balances until the next time the wallet is unlocked. This + problem was not limited to failing to recognize the spend; it was possible for + the shown balance to increase by the amount of change from a spend, without + deducting the spent amount. + +- While encrypted wallets prevent spending of funds, they do not maintain the + shielding properties of JoinSplits (due to the need to detect spends). That + is, someone with access to an encrypted wallet.dat has full visibility of + your entire transaction graph (other than newly-detected spends, which suffer + from the earlier issue). + +- We were concerned about the resistance of the algorithm used to derive wallet + encryption keys (inherited from [Bitcoin](https://bitcoin.org/en/secure-your-wallet)) + to dictionary attacks by a powerful attacker. If and when we re-enable wallet + encryption, it is likely to be with a modern passphrase-based key derivation + algorithm designed for greater resistance to dictionary attack, such as Argon2i. + +You should use full-disk encryption (or encryption of your home directory) to +protect your wallet at rest, and should assume (even unprivileged) users who are +running on your OS can read your wallet.dat file. + +Side-Channel Attacks +-------------------- + +This implementation of Zcash is not resistant to side-channel attacks. You +should assume (even unprivileged) users who are running on the hardware, or who +are physically near the hardware, that your `zcashd` process is running on will +be able to: + +- Determine the values of your secret spending keys, as well as which notes you + are spending, by observing cache side-channels as you perform a JoinSplit + operation. This is due to probable side-channel leakage in the libsnark + proving machinery. + +- Determine which notes you own by observing cache side-channel information + leakage from the incremental witnesses as they are updated with new notes. + +- Determine which notes you own by observing the trial decryption process of + each note ciphertext on the blockchain. + +You should ensure no other users have the ability to execute code (even +unprivileged) on the hardware your `zcashd` process runs on until these +vulnerabilities are fully analyzed and fixed. + +REST Interface +-------------- + +The REST interface is a feature inherited from upstream Bitcoin. By default, +it is disabled. We do not recommend you enable it until it has undergone a +security review. + +RPC Interface +--------------- + +Users should choose a strong RPC password. If no RPC username and password are set, zcashd will not start and will print an error message with a suggestion for a strong random password. If the client knows the RPC password, they have at least full access to the node. In addition, certain RPC commands can be misused to overwrite files and/or take over the account that is running zcashd. (In the future we may restrict these commands, but full node access – including the ability to spend from and export keys held by the wallet – would still be possible unless wallet methods are disabled.) + +Users should also refrain from changing the default setting that only allows RPC connections from localhost. Allowing connections from remote hosts would enable a MITM to execute arbitrary RPC commands, which could lead to compromise of the account running zcashd and loss of funds. For multi-user services that use one or more zcashd instances on the backend, the parameters passed in by users should be controlled to prevent confused-deputy attacks which could spend from any keys held by that zcashd. + +Block Chain Reorganization: Major Differences +------------------------------------------------- + +Users should be aware of new behavior in Zcash that differs significantly from Bitcoin: in the case of a block chain reorganization, Bitcoin's coinbase maturity rule helps to ensure that any reorganization shorter than the maturity interval will not invalidate any of the rolled-back transactions. Zcash keeps Bitcoin's 100-block maturity interval for generation transactions, but because JoinSplits must be anchored within a block, this provides more limited protection against transactions becoming invalidated. In the case of a block chain reorganization for Zcash, all JoinSplits which were anchored within the reorganization interval and any transactions that depend on them will become invalid, rolling back transactions and reverting funds to the original owner. The transaction rebroadcast mechanism inherited from Bitcoin will not successfully rebroadcast transactions depending on invalidated JoinSplits if the anchor needs to change. The creator of an invalidated JoinSplit, as well as the creators of all transactions dependent on it, must rebroadcast the transactions themselves. + +Receivers of funds from a JoinSplit can mitigate the risk of relying on funds received from transactions that may be rolled back by using a higher minconf (minimum number of confirmations). + +Logging z_* RPC calls +--------------------- + +The option `-debug=zrpc` covers logging of the z_* calls. This will reveal information about private notes which you might prefer not to disclose. For example, when calling `z_sendmany` to create a shielded transaction, input notes are consumed and new output notes are created. + +The option `-debug=zrpcunsafe` covers logging of sensitive information in z_* calls which you would only need for debugging and audit purposes. For example, if you want to examine the memo field of a note being spent. + +Private spending keys for z addresses are never logged. + +Potentially-Missing Required Modifications +------------------------------------------ + +In addition to potential mistakes in code we added to Bitcoin Core, and +potential mistakes in our modifications to Bitcoin Core, it is also possible +that there were potential changes we were supposed to make to Bitcoin Core but +didn't, either because we didn't even consider making those changes, or we ran +out of time. We have brainstormed and documented a variety of such possibilities +in [issue #826](https://github.com/zcash/zcash/issues/826), and believe that we +have changed or done everything that was necessary for the 1.0.0 launch. Users +may want to review this list themselves. diff --git a/doc/shield-coinbase.md b/doc/shield-coinbase.md index f023915b0..d3986fec7 100644 --- a/doc/shield-coinbase.md +++ b/doc/shield-coinbase.md @@ -1,5 +1,101 @@ # Shielding Coinbase UTXOs -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/shield_coinbase.html +**Summary** + +Use `z_shieldcoinbase` RPC call to shield coinbase UTXOs. + +**Who should read this document** + +Miners, Mining pools, Online wallets + +## Background + +The current Zcash protocol includes a consensus rule that coinbase rewards must be sent to a shielded address. + +## User Experience Challenges + +A user can use the z_sendmany RPC call to shield coinbase funds, but the call was not designed for sweeping up many UTXOs, and offered a suboptimal user experience. + +If customers send mining pool payouts to their online wallet, the service provider must sort through UTXOs to correctly determine the non-coinbase UTXO funds that can be withdrawn or transferred by customers to another transparent address. + +## Solution + +The z_shieldcoinbase call makes it easy to sweep up coinbase rewards from multiple coinbase UTXOs across multiple coinbase reward addresses. + + z_shieldcoinbase fromaddress toaddress (fee) (limit) + +The default fee is 0.0010000 ZEC and the default limit on the maximum number of UTXOs to shield is 50. + +## Examples + +Sweep up coinbase UTXOs from a transparent address you use for mining: + + zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress + +Sweep up coinbase UTXOs from multiple transparent addresses to a shielded address: + + zcash-cli z_shieldcoinbase "*" zMyPrivateAddress + +Sweep up with a fee of 1.23 ZEC: + + zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress 1.23 + +Sweep up with a fee of 0.1 ZEC and set limit on the maximum number of UTXOs to shield at 25: + + zcash-cli z_shieldcoinbase "*" zMyPrivateAddress 0.1 25 + +### Asynchronous Call + +The `z_shieldcoinbase` RPC call is an asynchronous call, so you can queue up multiple operations. + +When you invoke + + zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress + +JSON will be returned immediately, with the following data fields populated: + +- operationid: a temporary id to use with `z_getoperationstatus` and `z_getoperationresult` to get the status and result of the operation. +- shieldedUTXOs: number of coinbase UTXOs being shielded +- shieldedValue: value of coinbase UTXOs being shielded. +- remainingUTXOs: number of coinbase UTXOs still available for shielding. +- remainingValue: value of coinbase UTXOs still available for shielding + +### Locking UTXOs + +The `z_shieldcoinbase` call will lock any selected UTXOs. This prevents the selected UTXOs which are already queued up from being selected for any other send operation. If the `z_shieldcoinbase` call fails, any locked UTXOs are unlocked. + +You can use the RPC call `lockunspent` to see which UTXOs have been locked. You can also use this call to unlock any UTXOs in the event of an unexpected system failure which leaves UTXOs in a locked state. + +### Limits, Performance and Transaction Confirmation + +The number of coinbase UTXOs selected for shielding can be adjusted by setting the limit parameter. The default value is 50. + +If the limit parameter is set to zero, the zcashd `mempooltxinputlimit` option will be used instead, where the default value for `mempooltxinputlimit` is zero, which means no limit. + +Any limit is constrained by a hard limit due to the consensus rule defining a maximum transaction size of 100,000 bytes. + +In general, the more UTXOs that are selected, the longer it takes for the transaction to be verified. Due to the quadratic hashing problem, some miners use the `mempooltxinputlimit` option to reject transactions with a large number of UTXO inputs. + +Currently, as of November 2017, there is no commonly agreed upon limit, but as a rule of thumb (a form of emergent consensus) if a transaction has less than 100 UTXO inputs, the transaction will be mined promptly by the majority of mining pools, but if it has many more UTXO inputs, such as 500, it might take several days to be mined by a miner who has higher or no limits. + +### Anatomy of a z_shieldcoinbase transaction + +The transaction created is a shielded transaction. It consists of a single joinsplit, which consumes coinbase UTXOs as input, and deposits value at a shielded address, minus any fee. + +The number of coinbase UTXOs is determined by a user configured limit. + +If no limit is set (in the case when limit parameter and `mempooltxinputlimit` options are set to zero) the behaviour of z_shieldcoinbase is to consume as many UTXOs as possible, with `z_shieldcoinbase` constructing a transaction up to the size limit of 100,000 bytes. + +As a result, the maximum number of inputs that can be selected is: + +- P2PKH coinbase UTXOs ~ 662 +- 2-of-3 multisig P2SH coinbase UTXOs ~ 244. + +Here is an example of using `z_shieldcoinbase` on testnet to shield multi-sig coinbase UTXOs. + +- Block 141042 is almost ~2 MB in size (the maximum size for a block) and contains 1 coinbase reward transaction and 20 transactions, each indivually created by a call to z_shieldcoinbase. + - https://explorer.testnet.z.cash/block/0050552a78e97c89f666713c8448d49ad1d7263274422272696187dedf6c0d03 +- Drilling down into a transaction, you can see there is one joinsplit, with 244 inputs (vin) and 0 outputs (vout). + - https://explorer.testnet.z.cash/tx/cf4f3da2e434f68b6e361303403344e22a9ff9a8fda9abc180d9520d0ca6527d + -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/shield_coinbase.rst \ No newline at end of file diff --git a/doc/tor.md b/doc/tor.md index 970c6f12f..d9ddb87e2 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -1,6 +1,149 @@ +*** Warning: Do not assume Tor support does the correct thing in Zcash; better Tor support is a future feature goal. *** + TOR SUPPORT IN ZCASH ==================== -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/tor.html +It is possible to run Zcash as a Tor hidden service, and connect to such services. -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/tor.rst \ No newline at end of file +The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly +configure Tor. + + +1. Run Zcash behind a Tor proxy +------------------------------- + +The first step is running Zcash behind a Tor proxy. This will already make all +outgoing connections be anonymized, but more is possible. + + -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy + server will be used to try to reach .onion addresses as well. + + -onion=ip:port Set the proxy server to use for Tor hidden services. You do not + need to set this if it's the same as -proxy. You can use -noonion + to explicitly disable access to hidden service. + + -listen When using -proxy, listening is disabled by default. If you want + to run a hidden service (see next section), you'll need to enable + it explicitly. + + -connect=X When behind a Tor proxy, you can specify .onion addresses instead + -addnode=X of IP addresses or hostnames in these parameters. It requires + -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with + other P2P nodes. + +In a typical situation, this suffices to run behind a Tor proxy: + + ./zcashd -proxy=127.0.0.1:9050 + + +2. Run a Zcash hidden server +---------------------------- + +If you configure your Tor system accordingly, it is possible to make your node also +reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent +config file): + + HiddenServiceDir /var/lib/tor/zcash-service/ + HiddenServicePort 8233 127.0.0.1:8233 + HiddenServicePort 18233 127.0.0.1:18233 + +The directory can be different of course, but (both) port numbers should be equal to +your zcashd's P2P listen port (8233 by default). + + -externalip=X You can tell Zcash about its publicly reachable address using + this option, and this can be a .onion address. Given the above + configuration, you can find your onion address in + /var/lib/tor/zcash-service/hostname. Onion addresses are given + preference for your node to advertize itself with, for connections + coming from unroutable addresses (such as 127.0.0.1, where the + Tor proxy typically runs). + + -listen You'll need to enable listening for incoming connections, as this + is off by default behind a proxy. + + -discover When -externalip is specified, no attempt is made to discover local + IPv4 or IPv6 addresses. If you want to run a dual stack, reachable + from both Tor and IPv4 (or IPv6), you'll need to either pass your + other addresses using -externalip, or explicitly enable -discover. + Note that both addresses of a dual-stack system may be easily + linkable using traffic analysis. + +In a typical situation, where you're only reachable via Tor, this should suffice: + + ./zcashd -proxy=127.0.0.1:9050 -externalip=zctestseie6wxgio.onion -listen + +(obviously, replace the Onion address with your own). It should be noted that you still +listen on all devices and another node could establish a clearnet connection, when knowing +your address. To mitigate this, additionally bind the address of your Tor proxy: + + ./zcashd ... -bind=127.0.0.1 + +If you don't care too much about hiding your node, and want to be reachable on IPv4 +as well, use `discover` instead: + + ./zcashd ... -discover + +and open port 8233 on your firewall (or use -upnp). + +If you only want to use Tor to reach onion addresses, but not use it as a proxy +for normal IPv4/IPv6 communication, use: + + ./zcashd -onion=127.0.0.1:9050 -externalip=zctestseie6wxgio.onion -discover + + +3. Automatically listen on Tor +-------------------------------- + +Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket +API, to create and destroy 'ephemeral' hidden services programmatically. +Zcash has been updated to make use of this. + +This means that if Tor is running (and proper authentication has been configured), +Zcash automatically creates a hidden service to listen on. Zcash will also use Tor +automatically to connect to other .onion nodes if the control socket can be +successfully opened. This will positively affect the number of available .onion +nodes and their usage. + +This new feature is enabled by default if Zcash is listening (`-listen`), and +requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0` +and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings. +To show verbose debugging information, pass `-debug=tor`. + +Connecting to Tor's control socket API requires one of two authentication methods to be +configured. For cookie authentication the user running zcashd must have write access +to the `CookieAuthFile` specified in Tor configuration. In some cases this is +preconfigured and the creation of a hidden service is automatic. If permission problems +are seen with `-debug=tor` they can be resolved by adding both the user running tor and +the user running zcashd to the same group and setting permissions appropriately. On +Debian-based systems the user running zcashd can be added to the debian-tor group, +which has the appropriate permissions. An alternative authentication method is the use +of the `-torpassword` flag and a `hash-password` which can be enabled and specified in +Tor configuration. + + +4. Connect to a Zcash hidden server +----------------------------------- + +To test your set-up, you might want to try connecting via Tor on a different computer to just a +a single Zcash hidden server. Launch zcashd as follows: + + ./zcashd -onion=127.0.0.1:9050 -connect=zctestseie6wxgio.onion + +Now use zcash-cli to verify there is only a single peer connection. + + zcash-cli getpeerinfo + + [ + { + "id" : 1, + "addr" : "zctestseie6wxgio.onion:18233", + ... + "version" : 170002, + "subver" : "/MagicBean:1.0.0/", + ... + } + ] + +To connect to multiple Tor nodes, use: + + ./zcashd -onion=127.0.0.1:9050 -addnode=zctestseie6wxgio.onion -dnsseed=0 -onlynet=onion diff --git a/doc/unit-tests.md b/doc/unit-tests.md index 1864240ed..9410b4407 100644 --- a/doc/unit-tests.md +++ b/doc/unit-tests.md @@ -1,6 +1,17 @@ Compiling/running automated tests --------------------------------- -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/development_guidelines.html#testing +Automated tests will be automatically compiled if dependencies were met in configure +and tests weren't explicitly disabled. -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/development_guidelines.rst +There are two scripts for running tests: + +* ``qa/zcash/full_test_suite.py``, to run the main test suite +* ``qa/pull-tester/rpc-tests.sh``, to run the RPC tests. + +The main test suite uses two different testing frameworks. Tests using the Boost +framework are under ``src/test/``; tests using the Google Test/Google Mock +framework are under ``src/gtest/`` and ``src/wallet/gtest/``. The latter framework +is preferred for new Zcash unit tests. + +RPC tests are implemented in Python under the ``qa/rpc-tests/`` directory. diff --git a/doc/wallet-backup.md b/doc/wallet-backup.md index e83139cae..02454db72 100644 --- a/doc/wallet-backup.md +++ b/doc/wallet-backup.md @@ -1,5 +1,91 @@ # Wallet Backup Instructions -This document has been relocated to https://zcash.readthedocs.io/en/latest/rtd_pages/wallet_backup.html +## Overview -The source for this document is available at https://gitlab.com/zcash-docs/zcash-docs/blob/master/source/rtd_pages/wallet_backup.rst \ No newline at end of file +Backing up your Zcash private keys is the best way to be proactive about preventing loss of access to your ZEC. + +Problems resulting from bugs in the code, user error, device failure, etc. may lead to losing access to your wallet (and as a result, the private keys of addresses which are required to spend from them). + +No matter what the cause of a corrupted or lost wallet could be, we highly recommend all users backup on a regular basis. Anytime a new address in the wallet is generated, we recommending making a new backup so all private keys for addresses in your wallet are safe. + +Note that a backup is a duplicate of data needed to spend ZEC so where you keep your backup(s) is another important consideration. You should not store backups where they would be equally or increasingly susceptible to loss or theft. + +## Instructions for backing up your wallet and/or private keys + +These instructions are specific for the officially supported Zcash Linux client. For backing up with third-party wallets, please consult with user guides or support channels provided for those services. + +There are multiple ways to make sure you have at least one other copy of the private keys needed to spend your ZEC and view your shielded ZEC. + +For all methods, you will need to include an export directory setting in your config file (`zcash.conf` located in the data directory which is `~/.zcash/` unless it's been overridden with `datadir=` setting): + +`exportdir=path/to/chosen/export/directory` + +You may chose any directory within the home directory as the location for export & backup files. If the directory doesn't exist, it will be created. + +Note that zcashd will need to be stopped and restarted for edits in the config file to take effect. + +### Using `backupwallet` + +To create a backup of your wallet, use: + +`zcash-cli backupwallet `. + +The backup will be an exact copy of the current state of your wallet.dat file stored in the export directory you specified in the config file. The file path will also be returned. + +If you generate a new Zcash address, it will not be reflected in the backup file. + +If your original `wallet.dat` file becomes inaccessible for whatever reason, you can use your backup by copying it into your data directory and renaming the copy to `wallet.dat`. + +### Using `z_exportwallet` & `z_importwallet` + +If you prefer to have an export of your private keys in human readable format, you can use: + +`zcash-cli z_exportwallet ` + +This will generate a file in the export directory listing all transparent and shielded private keys with their associated public addresses. The file path will be returned in the command line. + +To import keys into a wallet which were previously exported to a file, use: + +`zcash-cli z_importwallet ` + +### Using `z_exportkey`, `z_importkey`, `dumpprivkey` & `importprivkey` + +If you prefer to export a single private key for a shielded address, you can use: + +`zcash-cli z_exportkey ` + +This will return the private key and will not create a new file. + +For exporting a single private key for a transparent address, you can use the command inherited from Bitcoin: + +`zcash-cli dumpprivkey ` + +This will return the private key and will not create a new file. + +To import a private key for a shielded address, use: + +`zcash-cli z_importkey ` + +This will add the key to your wallet and rescan the wallet for associated transactions if it is not already part of the wallet. + +The rescanning process can take a few minutes for a new private key. To skip it, instead use: + +`zcash-cli z_importkey no` + +For other instructions on fine-tuning the wallet rescan, see the command's help documentation: + +`zcash-cli help z_importkey` + +To import a private key for a transparent address, use: + +`zcash-cli importprivkey ` + +This has the same functionality as `z_importkey` but works with transparent addresses. + +See the command's help documentation for instructions on fine-tuning the wallet rescan: + +`zcash-cli help importprivkey` + +### Using `dumpwallet` + +This command inherited from Bitcoin is deprecated. It will export private keys in a similar fashion as `z_exportwallet` but only for transparent addresses. \ No newline at end of file From e9234ed50f5929f2261b7cb9d71ca36f777dadb7 Mon Sep 17 00:00:00 2001 From: Kris Nuttycombe Date: Thu, 12 May 2022 08:53:58 -0600 Subject: [PATCH 2/7] Fix documentation line wrapping --- doc/security-warnings.md | 73 ++++++++++++++++++++++++++++---------- doc/shield-coinbase.md | 76 +++++++++++++++++++++++++++++----------- 2 files changed, 110 insertions(+), 39 deletions(-) diff --git a/doc/security-warnings.md b/doc/security-warnings.md index 556a55c4a..8516dc734 100644 --- a/doc/security-warnings.md +++ b/doc/security-warnings.md @@ -24,9 +24,9 @@ Wallet encryption is disabled, for several reasons: - Encrypted wallets are unable to correctly detect shielded spends (due to the nature of unlinkability of JoinSplits) and can incorrectly show larger available shielded balances until the next time the wallet is unlocked. This - problem was not limited to failing to recognize the spend; it was possible for - the shown balance to increase by the amount of change from a spend, without - deducting the spent amount. + problem was not limited to failing to recognize the spend; it was possible + for the shown balance to increase by the amount of change from a spend, + without deducting the spent amount. - While encrypted wallets prevent spending of funds, they do not maintain the shielding properties of JoinSplits (due to the need to detect spends). That @@ -35,14 +35,15 @@ Wallet encryption is disabled, for several reasons: from the earlier issue). - We were concerned about the resistance of the algorithm used to derive wallet - encryption keys (inherited from [Bitcoin](https://bitcoin.org/en/secure-your-wallet)) - to dictionary attacks by a powerful attacker. If and when we re-enable wallet - encryption, it is likely to be with a modern passphrase-based key derivation - algorithm designed for greater resistance to dictionary attack, such as Argon2i. + encryption keys (inherited from + [Bitcoin](https://bitcoin.org/en/secure-your-wallet)) to dictionary attacks + by a powerful attacker. If and when we re-enable wallet encryption, it is + likely to be with a modern passphrase-based key derivation algorithm designed + for greater resistance to dictionary attack, such as Argon2i. You should use full-disk encryption (or encryption of your home directory) to -protect your wallet at rest, and should assume (even unprivileged) users who are -running on your OS can read your wallet.dat file. +protect your wallet at rest, and should assume (even unprivileged) users who +are running on your OS can read your wallet.dat file. Side-Channel Attacks -------------------- @@ -77,23 +78,57 @@ security review. RPC Interface --------------- -Users should choose a strong RPC password. If no RPC username and password are set, zcashd will not start and will print an error message with a suggestion for a strong random password. If the client knows the RPC password, they have at least full access to the node. In addition, certain RPC commands can be misused to overwrite files and/or take over the account that is running zcashd. (In the future we may restrict these commands, but full node access – including the ability to spend from and export keys held by the wallet – would still be possible unless wallet methods are disabled.) +Users should choose a strong RPC password. If no RPC username and password are +set, zcashd will not start and will print an error message with a suggestion +for a strong random password. If the client knows the RPC password, they have +at least full access to the node. In addition, certain RPC commands can be +misused to overwrite files and/or take over the account that is running zcashd. +(In the future we may restrict these commands, but full node access – including +the ability to spend from and export keys held by the wallet – would still be +possible unless wallet methods are disabled.) -Users should also refrain from changing the default setting that only allows RPC connections from localhost. Allowing connections from remote hosts would enable a MITM to execute arbitrary RPC commands, which could lead to compromise of the account running zcashd and loss of funds. For multi-user services that use one or more zcashd instances on the backend, the parameters passed in by users should be controlled to prevent confused-deputy attacks which could spend from any keys held by that zcashd. +Users should also refrain from changing the default setting that only allows +RPC connections from localhost. Allowing connections from remote hosts would +enable a MITM to execute arbitrary RPC commands, which could lead to compromise +of the account running zcashd and loss of funds. For multi-user services that +use one or more zcashd instances on the backend, the parameters passed in by +users should be controlled to prevent confused-deputy attacks which could spend +from any keys held by that zcashd. Block Chain Reorganization: Major Differences ------------------------------------------------- -Users should be aware of new behavior in Zcash that differs significantly from Bitcoin: in the case of a block chain reorganization, Bitcoin's coinbase maturity rule helps to ensure that any reorganization shorter than the maturity interval will not invalidate any of the rolled-back transactions. Zcash keeps Bitcoin's 100-block maturity interval for generation transactions, but because JoinSplits must be anchored within a block, this provides more limited protection against transactions becoming invalidated. In the case of a block chain reorganization for Zcash, all JoinSplits which were anchored within the reorganization interval and any transactions that depend on them will become invalid, rolling back transactions and reverting funds to the original owner. The transaction rebroadcast mechanism inherited from Bitcoin will not successfully rebroadcast transactions depending on invalidated JoinSplits if the anchor needs to change. The creator of an invalidated JoinSplit, as well as the creators of all transactions dependent on it, must rebroadcast the transactions themselves. +Users should be aware of new behavior in Zcash that differs significantly from +Bitcoin: in the case of a block chain reorganization, Bitcoin's coinbase +maturity rule helps to ensure that any reorganization shorter than the maturity +interval will not invalidate any of the rolled-back transactions. Zcash keeps +Bitcoin's 100-block maturity interval for generation transactions, but because +JoinSplits must be anchored within a block, this provides more limited +protection against transactions becoming invalidated. In the case of a block +chain reorganization for Zcash, all JoinSplits which were anchored within the +reorganization interval and any transactions that depend on them will become +invalid, rolling back transactions and reverting funds to the original owner. +The transaction rebroadcast mechanism inherited from Bitcoin will not +successfully rebroadcast transactions depending on invalidated JoinSplits if +the anchor needs to change. The creator of an invalidated JoinSplit, as well as +the creators of all transactions dependent on it, must rebroadcast the +transactions themselves. -Receivers of funds from a JoinSplit can mitigate the risk of relying on funds received from transactions that may be rolled back by using a higher minconf (minimum number of confirmations). +Receivers of funds from a JoinSplit can mitigate the risk of relying on funds +received from transactions that may be rolled back by using a higher minconf +(minimum number of confirmations). Logging z_* RPC calls --------------------- -The option `-debug=zrpc` covers logging of the z_* calls. This will reveal information about private notes which you might prefer not to disclose. For example, when calling `z_sendmany` to create a shielded transaction, input notes are consumed and new output notes are created. +The option `-debug=zrpc` covers logging of the z_* calls. This will reveal +information about private notes which you might prefer not to disclose. For +example, when calling `z_sendmany` to create a shielded transaction, input +notes are consumed and new output notes are created. -The option `-debug=zrpcunsafe` covers logging of sensitive information in z_* calls which you would only need for debugging and audit purposes. For example, if you want to examine the memo field of a note being spent. +The option `-debug=zrpcunsafe` covers logging of sensitive information in z_* +calls which you would only need for debugging and audit purposes. For example, +if you want to examine the memo field of a note being spent. Private spending keys for z addresses are never logged. @@ -104,7 +139,7 @@ In addition to potential mistakes in code we added to Bitcoin Core, and potential mistakes in our modifications to Bitcoin Core, it is also possible that there were potential changes we were supposed to make to Bitcoin Core but didn't, either because we didn't even consider making those changes, or we ran -out of time. We have brainstormed and documented a variety of such possibilities -in [issue #826](https://github.com/zcash/zcash/issues/826), and believe that we -have changed or done everything that was necessary for the 1.0.0 launch. Users -may want to review this list themselves. +out of time. We have brainstormed and documented a variety of such +possibilities in [issue #826](https://github.com/zcash/zcash/issues/826), and +believe that we have changed or done everything that was necessary for the +1.0.0 launch. Users may want to review this list themselves. diff --git a/doc/shield-coinbase.md b/doc/shield-coinbase.md index d3986fec7..4ae14b635 100644 --- a/doc/shield-coinbase.md +++ b/doc/shield-coinbase.md @@ -10,21 +10,29 @@ Miners, Mining pools, Online wallets ## Background -The current Zcash protocol includes a consensus rule that coinbase rewards must be sent to a shielded address. +The current Zcash protocol includes a consensus rule that coinbase rewards must +be sent to a shielded address. ## User Experience Challenges -A user can use the z_sendmany RPC call to shield coinbase funds, but the call was not designed for sweeping up many UTXOs, and offered a suboptimal user experience. +A user can use the z_sendmany RPC call to shield coinbase funds, but the call +was not designed for sweeping up many UTXOs, and offered a suboptimal user +experience. -If customers send mining pool payouts to their online wallet, the service provider must sort through UTXOs to correctly determine the non-coinbase UTXO funds that can be withdrawn or transferred by customers to another transparent address. +If customers send mining pool payouts to their online wallet, the service +provider must sort through UTXOs to correctly determine the non-coinbase UTXO +funds that can be withdrawn or transferred by customers to another transparent +address. ## Solution -The z_shieldcoinbase call makes it easy to sweep up coinbase rewards from multiple coinbase UTXOs across multiple coinbase reward addresses. +The z_shieldcoinbase call makes it easy to sweep up coinbase rewards from +multiple coinbase UTXOs across multiple coinbase reward addresses. z_shieldcoinbase fromaddress toaddress (fee) (limit) -The default fee is 0.0010000 ZEC and the default limit on the maximum number of UTXOs to shield is 50. +The default fee is 0.0010000 ZEC and the default limit on the maximum number of +UTXOs to shield is 50. ## Examples @@ -32,7 +40,8 @@ Sweep up coinbase UTXOs from a transparent address you use for mining: zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress -Sweep up coinbase UTXOs from multiple transparent addresses to a shielded address: +Sweep up coinbase UTXOs from multiple transparent addresses to a shielded +address: zcash-cli z_shieldcoinbase "*" zMyPrivateAddress @@ -40,13 +49,15 @@ Sweep up with a fee of 1.23 ZEC: zcash-cli z_shieldcoinbase tMyMiningAddress zMyPrivateAddress 1.23 -Sweep up with a fee of 0.1 ZEC and set limit on the maximum number of UTXOs to shield at 25: +Sweep up with a fee of 0.1 ZEC and set limit on the maximum number of UTXOs to +shield at 25: zcash-cli z_shieldcoinbase "*" zMyPrivateAddress 0.1 25 ### Asynchronous Call -The `z_shieldcoinbase` RPC call is an asynchronous call, so you can queue up multiple operations. +The `z_shieldcoinbase` RPC call is an asynchronous call, so you can queue up +multiple operations. When you invoke @@ -54,7 +65,8 @@ When you invoke JSON will be returned immediately, with the following data fields populated: -- operationid: a temporary id to use with `z_getoperationstatus` and `z_getoperationresult` to get the status and result of the operation. +- operationid: a temporary id to use with `z_getoperationstatus` and + `z_getoperationresult` to get the status and result of the operation. - shieldedUTXOs: number of coinbase UTXOs being shielded - shieldedValue: value of coinbase UTXOs being shielded. - remainingUTXOs: number of coinbase UTXOs still available for shielding. @@ -62,29 +74,50 @@ JSON will be returned immediately, with the following data fields populated: ### Locking UTXOs -The `z_shieldcoinbase` call will lock any selected UTXOs. This prevents the selected UTXOs which are already queued up from being selected for any other send operation. If the `z_shieldcoinbase` call fails, any locked UTXOs are unlocked. +The `z_shieldcoinbase` call will lock any selected UTXOs. This prevents the +selected UTXOs which are already queued up from being selected for any other +send operation. If the `z_shieldcoinbase` call fails, any locked UTXOs are +unlocked. -You can use the RPC call `lockunspent` to see which UTXOs have been locked. You can also use this call to unlock any UTXOs in the event of an unexpected system failure which leaves UTXOs in a locked state. +You can use the RPC call `lockunspent` to see which UTXOs have been locked. +You can also use this call to unlock any UTXOs in the event of an unexpected +system failure which leaves UTXOs in a locked state. ### Limits, Performance and Transaction Confirmation -The number of coinbase UTXOs selected for shielding can be adjusted by setting the limit parameter. The default value is 50. +The number of coinbase UTXOs selected for shielding can be adjusted by setting +the limit parameter. The default value is 50. -If the limit parameter is set to zero, the zcashd `mempooltxinputlimit` option will be used instead, where the default value for `mempooltxinputlimit` is zero, which means no limit. +If the limit parameter is set to zero, the zcashd `mempooltxinputlimit` option +will be used instead, where the default value for `mempooltxinputlimit` is +zero, which means no limit. -Any limit is constrained by a hard limit due to the consensus rule defining a maximum transaction size of 100,000 bytes. +Any limit is constrained by a hard limit due to the consensus rule defining a +maximum transaction size of 100,000 bytes. -In general, the more UTXOs that are selected, the longer it takes for the transaction to be verified. Due to the quadratic hashing problem, some miners use the `mempooltxinputlimit` option to reject transactions with a large number of UTXO inputs. +In general, the more UTXOs that are selected, the longer it takes for the +transaction to be verified. Due to the quadratic hashing problem, some miners +use the `mempooltxinputlimit` option to reject transactions with a large number +of UTXO inputs. -Currently, as of November 2017, there is no commonly agreed upon limit, but as a rule of thumb (a form of emergent consensus) if a transaction has less than 100 UTXO inputs, the transaction will be mined promptly by the majority of mining pools, but if it has many more UTXO inputs, such as 500, it might take several days to be mined by a miner who has higher or no limits. +Currently, as of November 2017, there is no commonly agreed upon limit, but as +a rule of thumb (a form of emergent consensus) if a transaction has less than +100 UTXO inputs, the transaction will be mined promptly by the majority of +mining pools, but if it has many more UTXO inputs, such as 500, it might take +several days to be mined by a miner who has higher or no limits. ### Anatomy of a z_shieldcoinbase transaction -The transaction created is a shielded transaction. It consists of a single joinsplit, which consumes coinbase UTXOs as input, and deposits value at a shielded address, minus any fee. +The transaction created is a shielded transaction. It consists of a single +joinsplit, which consumes coinbase UTXOs as input, and deposits value at a +shielded address, minus any fee. The number of coinbase UTXOs is determined by a user configured limit. -If no limit is set (in the case when limit parameter and `mempooltxinputlimit` options are set to zero) the behaviour of z_shieldcoinbase is to consume as many UTXOs as possible, with `z_shieldcoinbase` constructing a transaction up to the size limit of 100,000 bytes. +If no limit is set (in the case when limit parameter and `mempooltxinputlimit` +options are set to zero) the behaviour of z_shieldcoinbase is to consume as +many UTXOs as possible, with `z_shieldcoinbase` constructing a transaction up +to the size limit of 100,000 bytes. As a result, the maximum number of inputs that can be selected is: @@ -93,9 +126,12 @@ As a result, the maximum number of inputs that can be selected is: Here is an example of using `z_shieldcoinbase` on testnet to shield multi-sig coinbase UTXOs. -- Block 141042 is almost ~2 MB in size (the maximum size for a block) and contains 1 coinbase reward transaction and 20 transactions, each indivually created by a call to z_shieldcoinbase. +- Block 141042 is almost ~2 MB in size (the maximum size for a block) and + contains 1 coinbase reward transaction and 20 transactions, each indivually + created by a call to z_shieldcoinbase. - https://explorer.testnet.z.cash/block/0050552a78e97c89f666713c8448d49ad1d7263274422272696187dedf6c0d03 -- Drilling down into a transaction, you can see there is one joinsplit, with 244 inputs (vin) and 0 outputs (vout). +- Drilling down into a transaction, you can see there is one joinsplit, with + 244 inputs (vin) and 0 outputs (vout). - https://explorer.testnet.z.cash/tx/cf4f3da2e434f68b6e361303403344e22a9ff9a8fda9abc180d9520d0ca6527d From ad72a606c272ad9304d29d76c1c8df170fad49f1 Mon Sep 17 00:00:00 2001 From: Kris Nuttycombe Date: Thu, 12 May 2022 09:50:31 -0600 Subject: [PATCH 3/7] Backport changes from zcash.readthedocs.io --- doc/files.md | 37 ++++++++----- doc/security-warnings.md | 21 +++---- doc/wallet-backup.md | 116 ++++++++++++++++++++++++++++----------- 3 files changed, 116 insertions(+), 58 deletions(-) diff --git a/doc/files.md b/doc/files.md index 2d3787912..dfde08fb2 100644 --- a/doc/files.md +++ b/doc/files.md @@ -1,14 +1,23 @@ -* zcash.conf: contains configuration settings for zcashd -* zcashd.pid: stores the process id of zcashd while running -* blocks/blk000??.dat: block data (custom, 128 MiB per file) -* blocks/rev000??.dat; block undo data (custom) -* blocks/index/*; block index (LevelDB) -* chainstate/*; block chain state database (LevelDB) -* database/*: BDB database environment -* db.log: wallet database log file -* debug.log: contains debug information and general logging generated by zcashd -* fee_estimates.dat: stores statistics used to estimate minimum transaction fees and priorities required for confirmation -* peers.dat: peer IP address database (custom format) -* wallet.dat: personal wallet (BDB) with keys and transactions -* .cookie: session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown): since 0.12.0 -* onion_private_key: cached Tor hidden service private key for `-listenonion`: since 0.12.0 +Data Directory Files +==================== + +Files within the zcashd data directory (``~/.zcash/``) on Linux unless otherwise specified) include: + +| File | Description +|-----------------------|-------------- +|``zcash.conf`` | contains configuration settings for zcashd +|``zcashd.pid`` | stores the process id of zcashd while running +|``blocks/blk000*.dat`` | block data (custom, 128 MiB per file) +|``blocks/rev000*.dat`` | block undo data (custom) +|``blocks/index/*`` | block index (LevelDB) +|``chainstate/*`` | block chain state database (LevelDB) +|``database/*`` | BDB database environment +|``db.log`` | wallet database log file +|``debug.log`` | contains debug information and general logging generated by zcashd +|``fee_estimates.dat`` | stores statistics used to estimate minimum transaction fees and priorities required for confirmation +|``peers.dat`` | peer IP address database (custom format) +|``wallet.dat`` | personal wallet (BDB) with keys and transactions (keep private, back this up!) +|``.cookie`` | session RPC authentication cookie (written at start when cookie authentication is used, deleted on shutdown) +|``.lock`` | data directory lock file (empty) +|``testnet3/*`` | contains testnet versions of these files, except ``zcash.conf``, if running ``-testnet`` +|``onion_private_key`` | cached Tor hidden service private key for ``-listenonion`` diff --git a/doc/security-warnings.md b/doc/security-warnings.md index 8516dc734..62beeb4fb 100644 --- a/doc/security-warnings.md +++ b/doc/security-warnings.md @@ -1,5 +1,5 @@ Security Warnings -==================== +================= Security Audit -------------- @@ -9,12 +9,12 @@ announcements, audit results and other general security information, see https://z.cash/support/security.html x86-64 Linux Only ------------------------ +----------------- -There are [known bugs](https://github.com/scipr-lab/libsnark/issues/26) which -make proving keys generated on 64-bit systems unusable on 32-bit and big-endian -systems. It's unclear if a warning will be issued in this case, or if the -proving system will be silently compromised. +There are [known bugs](https://github.com/scipr-lab/libsnark/issues/26/) +which make proving keys generated on 64-bit systems unusable on 32-bit and +big-endian systems. It's unclear if a warning will be issued in this case, or +if the proving system will be silently compromised. Wallet Encryption ----------------- @@ -50,8 +50,8 @@ Side-Channel Attacks This implementation of Zcash is not resistant to side-channel attacks. You should assume (even unprivileged) users who are running on the hardware, or who -are physically near the hardware, that your `zcashd` process is running on will -be able to: +are physically near the hardware, that your `zcashd` process is running on +will be able to: - Determine the values of your secret spending keys, as well as which notes you are spending, by observing cache side-channels as you perform a JoinSplit @@ -75,9 +75,6 @@ The REST interface is a feature inherited from upstream Bitcoin. By default, it is disabled. We do not recommend you enable it until it has undergone a security review. -RPC Interface ---------------- - Users should choose a strong RPC password. If no RPC username and password are set, zcashd will not start and will print an error message with a suggestion for a strong random password. If the client knows the RPC password, they have @@ -96,7 +93,7 @@ users should be controlled to prevent confused-deputy attacks which could spend from any keys held by that zcashd. Block Chain Reorganization: Major Differences -------------------------------------------------- +--------------------------------------------- Users should be aware of new behavior in Zcash that differs significantly from Bitcoin: in the case of a block chain reorganization, Bitcoin's coinbase diff --git a/doc/wallet-backup.md b/doc/wallet-backup.md index 02454db72..2e53d3737 100644 --- a/doc/wallet-backup.md +++ b/doc/wallet-backup.md @@ -2,90 +2,142 @@ ## Overview -Backing up your Zcash private keys is the best way to be proactive about preventing loss of access to your ZEC. +Backing up your Zcash private keys is the best way to be proactive about +preventing loss of access to your ZEC. -Problems resulting from bugs in the code, user error, device failure, etc. may lead to losing access to your wallet (and as a result, the private keys of addresses which are required to spend from them). +Problems resulting from bugs in the code, user error, device failure, etc. may +lead to losing access to your wallet (and as a result, the private keys of +addresses which are required to spend from them). -No matter what the cause of a corrupted or lost wallet could be, we highly recommend all users backup on a regular basis. Anytime a new address in the wallet is generated, we recommending making a new backup so all private keys for addresses in your wallet are safe. +No matter what the cause of a corrupted or lost wallet could be, we highly +recommend all users backup on a regular basis. Anytime a new address in the +wallet is generated, we recommending making a new backup so all private keys +for addresses in your wallet are safe. -Note that a backup is a duplicate of data needed to spend ZEC so where you keep your backup(s) is another important consideration. You should not store backups where they would be equally or increasingly susceptible to loss or theft. +Note that a backup is a duplicate of data needed to spend ZEC so where you keep +your backup(s) is another important consideration. You should not store backups +where they would be equally or increasingly susceptible to loss or theft. ## Instructions for backing up your wallet and/or private keys -These instructions are specific for the officially supported Zcash Linux client. For backing up with third-party wallets, please consult with user guides or support channels provided for those services. +These instructions are specific for the officially supported Zcash Linux +client. For backing up with third-party wallets, please consult with user +guides or support channels provided for those services. -There are multiple ways to make sure you have at least one other copy of the private keys needed to spend your ZEC and view your shielded ZEC. +There are multiple ways to make sure you have at least one other copy of the +private keys needed to spend your ZEC and view your shielded ZEC. -For all methods, you will need to include an export directory setting in your config file (`zcash.conf` located in the data directory which is `~/.zcash/` unless it's been overridden with `datadir=` setting): +For all methods, you will need to include an export directory setting in your +config file (`zcash.conf` located in the data directory which is `~/.zcash/` +unless it's been overridden with `datadir=` setting): `exportdir=path/to/chosen/export/directory` -You may chose any directory within the home directory as the location for export & backup files. If the directory doesn't exist, it will be created. +You may chose any directory within the home directory as the location for +export & backup files. If the directory doesn't exist, it will be created. -Note that zcashd will need to be stopped and restarted for edits in the config file to take effect. +Note that zcashd will need to be stopped and restarted for edits in the config +file to take effect. ### Using `backupwallet` To create a backup of your wallet, use: -`zcash-cli backupwallet `. +```bash +$ zcash-cli backupwallet +``` -The backup will be an exact copy of the current state of your wallet.dat file stored in the export directory you specified in the config file. The file path will also be returned. +The backup will be an exact copy of the current state of your wallet.dat file +stored in the export directory you specified in the config file. The file path +will also be returned. -If you generate a new Zcash address, it will not be reflected in the backup file. +If you generate a new Zcash address, it will not be reflected in the backup +file. -If your original `wallet.dat` file becomes inaccessible for whatever reason, you can use your backup by copying it into your data directory and renaming the copy to `wallet.dat`. +If your original `wallet.dat` file becomes inaccessible for whatever reason, +you can use your backup by copying it into your data directory and renaming the +copy to `wallet.dat`. ### Using `z_exportwallet` & `z_importwallet` -If you prefer to have an export of your private keys in human readable format, you can use: +If you prefer to have an export of your private keys in human readable format, +you can use: -`zcash-cli z_exportwallet ` +```bash +$ zcash-cli z_exportwallet ` +``` -This will generate a file in the export directory listing all transparent and shielded private keys with their associated public addresses. The file path will be returned in the command line. +This will generate a file in the export directory listing all transparent and +shielded private keys with their associated public addresses. The file path +will be returned in the command line. To import keys into a wallet which were previously exported to a file, use: -`zcash-cli z_importwallet ` +```bash +$ zcash-cli z_importwallet +``` ### Using `z_exportkey`, `z_importkey`, `dumpprivkey` & `importprivkey` -If you prefer to export a single private key for a shielded address, you can use: +If you prefer to export a single private key for a shielded address, you can +use: -`zcash-cli z_exportkey ` +```bash +$ zcash-cli z_exportkey +``` This will return the private key and will not create a new file. -For exporting a single private key for a transparent address, you can use the command inherited from Bitcoin: +For exporting a single private key for a transparent address, you can use the +command inherited from Bitcoin: -`zcash-cli dumpprivkey ` +```bash +$ zcash-cli dumpprivkey +``` This will return the private key and will not create a new file. To import a private key for a shielded address, use: -`zcash-cli z_importkey ` +```bash +$ zcash-cli z_importkey +``` -This will add the key to your wallet and rescan the wallet for associated transactions if it is not already part of the wallet. +This will add the key to your wallet and rescan the wallet for associated +transactions if it is not already part of the wallet. -The rescanning process can take a few minutes for a new private key. To skip it, instead use: +The rescanning process can take a few minutes for a new private key. To skip +it, instead use: -`zcash-cli z_importkey no` +```bash +$ zcash-cli z_importkey no +``` -For other instructions on fine-tuning the wallet rescan, see the command's help documentation: +For other instructions on fine-tuning the wallet rescan, see the command's help +documentation: -`zcash-cli help z_importkey` +```bash +$ zcash-cli help z_importkey +``` To import a private key for a transparent address, use: -`zcash-cli importprivkey ` +```bash +$ zcash-cli importprivkey +``` -This has the same functionality as `z_importkey` but works with transparent addresses. +This has the same functionality as `z_importkey` but works with transparent +addresses. -See the command's help documentation for instructions on fine-tuning the wallet rescan: +See the command's help documentation for instructions on fine-tuning the wallet +rescan: -`zcash-cli help importprivkey` +```bash +$ zcash-cli help importprivkey +``` ### Using `dumpwallet` -This command inherited from Bitcoin is deprecated. It will export private keys in a similar fashion as `z_exportwallet` but only for transparent addresses. \ No newline at end of file +This command inherited from Bitcoin is deprecated and should not be used. It +will export private keys in a similar fashion as `z_exportwallet` but only for +transparent addresses. From 07d52d006e96369e0a95e6531b75951c23647f6a Mon Sep 17 00:00:00 2001 From: Greg Pfeil Date: Thu, 25 Aug 2022 10:41:11 -0600 Subject: [PATCH 4/7] Backport tor.md changes from readthedocs This is an separate from the other backporting because this was an upstream document, so isolating it helps with future backports from upstream. --- doc/tor.md | 396 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 268 insertions(+), 128 deletions(-) diff --git a/doc/tor.md b/doc/tor.md index d9ddb87e2..78b8f010e 100644 --- a/doc/tor.md +++ b/doc/tor.md @@ -1,149 +1,289 @@ -*** Warning: Do not assume Tor support does the correct thing in Zcash; better Tor support is a future feature goal. *** - -TOR SUPPORT IN ZCASH +Tor Support in Zcash ==================== -It is possible to run Zcash as a Tor hidden service, and connect to such services. +Tor can be used to provide a layer of network anonymity for Zcash users. +Additionally, Zcash users may chose to connect only to Tor hidden services, and +also to expose their own Tor hidden service to allow users to connect to them +over the Tor network. -The following directions assume you have a Tor proxy running on port 9050. Many distributions default to having a SOCKS proxy listening on port 9050, but others may not. In particular, the Tor Browser Bundle defaults to listening on port 9150. See [Tor Project FAQ:TBBSocksPort](https://www.torproject.org/docs/faq.html.en#TBBSocksPort) for how to properly -configure Tor. +0. Install Tor +-------------- + +The easiest way to install Tor is to use the +[Tor Browser Bundle](https://www.torproject.org/download/). For headless +installs, you probably want to install the Tor daemon. The Tor Project +provides [instructions](https://support.torproject.org/apt/) for doing this on +common Linux distributions. Note that the Tor Browser Bundle exposes a SOCKS +listener on tcp/9150 by default, while the Tor daemon exposes the SOCKS +listener on tcp/9050. For the purposes of the example below, we'll assume that +you're using the Tor daemon and that the SOCKS listener is on tcp/9050. + +1. Run zcashd over Tor +---------------------- + +Configuring zcashd to use a Tor SOCKS proxy will route all outgoing connections +over Tor. + +```bash +$ zcashd -proxy=127.0.0.1:9050 +``` + +Yay! Your zcashd node is now leveraging the Tor network to connect to other +zcashd nodes. But there's more fun to be had. By creating a +[Tor Hidden Service](https://2019.www.torproject.org/docs/faq.html.en#TorOnionServices). +you can help promote privacy for Zcash users by advertising your node's .onion +address to other Tor Zcash users. + +2. Expose your zcashd via a Tor hidden service (optional) +--------------------------------------------------------- + +Edit your /etc/tor/torrc (or equivalent config file) to map the hidden service +to your zcashd TCP listener. The directory can be whatever you like but the +port numbers should be equal to the zcashd p2p listen port (8233 by default). +An example is below. + +```yaml +############### This section is just for location-hidden services ### + +## Once you have configured a hidden service, you can look at the +## contents of the file ".../hidden_service/hostname" for the address +## to tell people. +## +## HiddenServicePort x y:z says to redirect requests on port x to the +## address y:z. + +# +# Placeholder for when zcashd adds support for Onion v3 addresses +#HiddenServiceDir /var/lib/tor/zcash_hidden_service_v3/ +#HiddenServiceVersion 3 +#HiddenServicePort 8233 127.0.0.1:8233 + +# use the generated v2 Onion hostname until v3 support is complete +HiddenServiceDir /var/lib/tor/zcash_hidden_service_v2/ +HiddenServiceVersion 2 +HiddenServicePort 8233 127.0.0.1:8233 +``` + +Note that zcashd does not yet support Onion v3 addresses, but will do so before +v2 addresses are removed from Tor. See [this +issue](https://github.com/zcash/zcash/issues/3051) for more information on +what's required to make zcashd support v3 Onion addresses. + +After making these edits to /etc/tor/torrc, restart tor to create the hidden +service hostname and keys. + +```bash +$ sudo systemctl restart tor +``` + +Then set a bash variable to provide your Onion service hostname to zcashd so it +can advertise your node to other Tor capable nodes on the Zcash network. + +```bash +$ export MY_ONION_HOSTNAME=`sudo cat /var/lib/tor/zcash_hidden_service_v2/hostname` +``` + +Now configure the zcashd node to use the Tor proxy, enable the TCP listener +(only on localhost), and advertise your onion address so that other nodes on +the Zcash network can connect to you over Tor. + +```bash +$ zcashd -proxy=127.0.0.1:9050 -externalip=$MY_ONION_HOSTNAME -listen -bind=127.0.0.1 -listenonion=0 +``` +zcashd flags used: + +- `-proxy=ip:port`: sets the proxy server. This must match the port IP and port + on which your Tor listener is configured. +- `-externalip=`: sets the publicly routable address that zcashd will + advertise to other zcash nodes. This can be an IPv4, IPv6 or .onion address. + Onion addresses are given preference for advertising and connections. Onionv3 + addresses are [not yet supported](https://github.com/zcash/zcash/issues/3051). +- `-listen`: Enable listening for incoming connections with this flag; + listening is off by default, but is needed in order for Tor to connect to + zcashd. +- `-bind=ip`: Bind (only) to this IP. Will bind to all interfaces by default + if ``listen=1``. +- `-listenonion=<0|1>`: Enable or disable autoconfiguration of Tor hidden + service via control socket API. Disabled in this example because we manually + configured the hidden service in /etc/tor/torrc. + +Once your node is up and running, you can use `zcash-cli` to verify that it +is properly connected to other Zcash nodes over the p2p network, and is +correctly advertising its Onion address to the network. + +```bash +$ zcash-cli getnetworkinfo +``` + +```javascript +{ + "version": 4020050, + "subversion": "/MagicBean:4.2.0/", + "protocolversion": 170013, + "connections": 9, + "networks": [ + { + "name": "ipv4", + "limited": true, + "reachable": false, + "proxy": "127.0.0.1:9050", + "proxy_randomize_credentials": true + }, + { + "name": "ipv6", + "limited": true, + "reachable": false, + "proxy": "127.0.0.1:9050", + "proxy_randomize_credentials": true + }, + { + "name": "onion", + "limited": false, + "reachable": true, + "proxy": "127.0.0.1:9050", + "proxy_randomize_credentials": true + } + ], + "relayfee": 0.00000100, + "localaddresses": [ + { + "address": "ynizm2wpla6ec22q.onion", + "port": 8233, + "score": 10 + } + ], +} +``` -1. Run Zcash behind a Tor proxy -------------------------------- - -The first step is running Zcash behind a Tor proxy. This will already make all -outgoing connections be anonymized, but more is possible. - - -proxy=ip:port Set the proxy server. If SOCKS5 is selected (default), this proxy - server will be used to try to reach .onion addresses as well. - - -onion=ip:port Set the proxy server to use for Tor hidden services. You do not - need to set this if it's the same as -proxy. You can use -noonion - to explicitly disable access to hidden service. - - -listen When using -proxy, listening is disabled by default. If you want - to run a hidden service (see next section), you'll need to enable - it explicitly. - - -connect=X When behind a Tor proxy, you can specify .onion addresses instead - -addnode=X of IP addresses or hostnames in these parameters. It requires - -seednode=X SOCKS5. In Tor mode, such addresses can also be exchanged with - other P2P nodes. - -In a typical situation, this suffices to run behind a Tor proxy: - - ./zcashd -proxy=127.0.0.1:9050 - - -2. Run a Zcash hidden server ----------------------------- - -If you configure your Tor system accordingly, it is possible to make your node also -reachable from the Tor network. Add these lines to your /etc/tor/torrc (or equivalent -config file): - - HiddenServiceDir /var/lib/tor/zcash-service/ - HiddenServicePort 8233 127.0.0.1:8233 - HiddenServicePort 18233 127.0.0.1:18233 - -The directory can be different of course, but (both) port numbers should be equal to -your zcashd's P2P listen port (8233 by default). - - -externalip=X You can tell Zcash about its publicly reachable address using - this option, and this can be a .onion address. Given the above - configuration, you can find your onion address in - /var/lib/tor/zcash-service/hostname. Onion addresses are given - preference for your node to advertize itself with, for connections - coming from unroutable addresses (such as 127.0.0.1, where the - Tor proxy typically runs). - - -listen You'll need to enable listening for incoming connections, as this - is off by default behind a proxy. - - -discover When -externalip is specified, no attempt is made to discover local - IPv4 or IPv6 addresses. If you want to run a dual stack, reachable - from both Tor and IPv4 (or IPv6), you'll need to either pass your - other addresses using -externalip, or explicitly enable -discover. - Note that both addresses of a dual-stack system may be easily - linkable using traffic analysis. - -In a typical situation, where you're only reachable via Tor, this should suffice: - - ./zcashd -proxy=127.0.0.1:9050 -externalip=zctestseie6wxgio.onion -listen - -(obviously, replace the Onion address with your own). It should be noted that you still -listen on all devices and another node could establish a clearnet connection, when knowing -your address. To mitigate this, additionally bind the address of your Tor proxy: - - ./zcashd ... -bind=127.0.0.1 - -If you don't care too much about hiding your node, and want to be reachable on IPv4 -as well, use `discover` instead: - - ./zcashd ... -discover - -and open port 8233 on your firewall (or use -upnp). - -If you only want to use Tor to reach onion addresses, but not use it as a proxy -for normal IPv4/IPv6 communication, use: - - ./zcashd -onion=127.0.0.1:9050 -externalip=zctestseie6wxgio.onion -discover - - -3. Automatically listen on Tor --------------------------------- +3. Dynamically Configure Onion Service (Optional) +------------------------------------------------- Starting with Tor version 0.2.7.1 it is possible, through Tor's control socket -API, to create and destroy 'ephemeral' hidden services programmatically. -Zcash has been updated to make use of this. +API, to create and destroy 'ephemeral' hidden services programmatically. zcashd +has been updated to make use of this. -This means that if Tor is running (and proper authentication has been configured), -Zcash automatically creates a hidden service to listen on. Zcash will also use Tor +This configuration could be used instead of manually configuring the Onion +service as in step 2 above. + +If Tor is running (and proper authentication has been configured), zcashd +automatically creates a hidden service to listen on. zcashd will also use Tor automatically to connect to other .onion nodes if the control socket can be -successfully opened. This will positively affect the number of available .onion -nodes and their usage. +successfully opened. -This new feature is enabled by default if Zcash is listening (`-listen`), and -requires a Tor connection to work. It can be explicitly disabled with `-listenonion=0` -and, if not disabled, configured using the `-torcontrol` and `-torpassword` settings. -To show verbose debugging information, pass `-debug=tor`. +This new feature is enabled by default if zcashd is listening (`-listen`) and +requires a Tor connection to work. It can be explicitly disabled with +`-listenonion=0` and, if not disabled, configured using the `-torcontrol` +and `-torpassword` settings. To show verbose debugging information, pass +`-debug=tor`. -Connecting to Tor's control socket API requires one of two authentication methods to be -configured. For cookie authentication the user running zcashd must have write access -to the `CookieAuthFile` specified in Tor configuration. In some cases this is -preconfigured and the creation of a hidden service is automatic. If permission problems -are seen with `-debug=tor` they can be resolved by adding both the user running tor and -the user running zcashd to the same group and setting permissions appropriately. On -Debian-based systems the user running zcashd can be added to the debian-tor group, -which has the appropriate permissions. An alternative authentication method is the use -of the `-torpassword` flag and a `hash-password` which can be enabled and specified in -Tor configuration. +Connecting to Tor's control socket API requires one of two authentication +methods to be configured: +1. Cookie authentication, which requires write access to the `CookieAuthFile` + specified in Tor configuration. In some cases, this is preconfigured and the + creation of a hidden service is automatic. If permission problems are seen + with `-debug=tor` they can be resolved by adding both the user running tor + and the user running zcashd to the same group and setting permissions + appropriately. On Debian-based systems the user running zcashd can be added + to the debian-tor group, which has the appropriate permissions. +2. Authentication with the `-torpassword` flag and a `hash-password`, which + can be enabled and specified in Tor configuration. -4. Connect to a Zcash hidden server ------------------------------------ +On Debian systems, where Tor is installed via APT, you can trivially permit +zcashd to connect to the Tor socket by adding the zcash user to the +`debian-tor` group. -To test your set-up, you might want to try connecting via Tor on a different computer to just a -a single Zcash hidden server. Launch zcashd as follows: +```bash +$ sudo usermod -aG debian-tor zcash +``` + +When properly configured, this will allow zcashd to automatically connect to +the Tor control socket API and configure an ephemeral hidden service. + +```bash +$ zcashd -debug=tor +``` + +``` +Feb 11 15:26:20.323 INFO main: tor: Got service ID tweustb4j6o3u5x7, advertizing service tweustb4j6o3u5x7.onion:8233 +Feb 11 15:26:20.323 DEBUG tor: tor: Cached service private key to /home/zcash/.zcash/onion_private_key +Feb 11 15:26:20.323 INFO main: AddLocal(tweustb4j6o3u5x7.onion:8233,4) +... +Feb 11 15:26:47.565 INFO main: ProcessMessages: advertizing address tweustb4j6o3u5x7.onion:8233 +``` + +4. Connect to a single Zcash Onion server +----------------------------------------- + +This invocation will start zcashd and connect via Tor to a single zcashd onion +server. + +Launch zcashd as follows: + +```bash +$ zcashd -onion=127.0.0.1:9050 -connect=ynizm2wpla6ec22q.onion +``` + +- `-onion=ip:port`: Use SOCKS5 proxy to reach peers via Tor hidden services. + This must match the port IP and port on which your Tor listener is + configured. +- `-connect=`: Connect only to the specified node(s); `-noconnect` + or `-connect=0` alone to disable automatic connections - ./zcashd -onion=127.0.0.1:9050 -connect=zctestseie6wxgio.onion Now use zcash-cli to verify there is only a single peer connection. - zcash-cli getpeerinfo +```bash +$ zcash-cli getpeerinfo +``` + +```javascript +[ + { + "id": 1, + "addr": "ynizm2wpla6ec22q.onion", + ... + "version": 170013, + "subver": "/MagicBean:4.2.0/", + "inbound": false, + ... + } +] +``` + +4. Connect to multiple Zcash Onion servers +------------------------------------------ + +This invocation will start zcashd, skip DNS seeding, connect via Tor to a +multiple zcashd onion servers, and also advertise your Onion server to other +Tor capable Zcash nodes. + +Launch zcashd as follows: + +```bash +$ export MY_ONION_HOSTNAME=`sudo cat /var/lib/tor/zcash_hidden_service_v2/hostname` +$ zcashd -listen -onion=127.0.0.1:9050 -addnode=ynizm2wpla6ec22q.onion -dnsseed=0 -onlynet=onion -externalip=$MY_ONION_HOSTNAME -bind=127.0.0.1 +``` + +zcashd flags used: + +- `-onion=ip:port`: Use SOCKS5 proxy to reach peers via Tor hidden services. + This must match the port IP and port on which your Tor listener is + configured. +- `-addnode=`: Add a node to connect to and attempt to keep the + connection open +- `-externalip=`: sets the publicly routable address that zcashd will + advertise to other zcash nodes. This can be an IPv4, IPv6 or .onion address. + Onion addresses are given preference for advertising and connections. Onionv3 + addresses are [not yet supported](https://github.com/zcash/zcash/issues/3051). +- `-listen`: Enable listening for incoming connections with this flag; + listening is off by default, but is needed in order for Tor to connect to + zcashd. +- `-bind=`: Bind (only) to this IP. Will bind to all interfaces by default + if `listen=1` and `bind` is not set. +- `-onlynet=`: Only connect to nodes in network `` (ipv4, ipv6 or + onion) - [ - { - "id" : 1, - "addr" : "zctestseie6wxgio.onion:18233", - ... - "version" : 170002, - "subver" : "/MagicBean:1.0.0/", - ... - } - ] -To connect to multiple Tor nodes, use: - ./zcashd -onion=127.0.0.1:9050 -addnode=zctestseie6wxgio.onion -dnsseed=0 -onlynet=onion From fbdfbae5934c30ddee6af284cc31af191b508049 Mon Sep 17 00:00:00 2001 From: Kris Nuttycombe Date: Thu, 12 May 2022 10:01:36 -0600 Subject: [PATCH 5/7] Move restored documentation into the zcashd book --- doc/book/src/SUMMARY.md | 14 ++++++++++---- doc/{ => book/src/dev}/dnsseed-policy.md | 0 doc/{ => book/src/user}/files.md | 0 doc/{ => book/src/user}/security-warnings.md | 0 doc/{ => book/src/user}/shield-coinbase.md | 0 doc/{ => book/src/user}/tor.md | 0 doc/{ => book/src/user}/wallet-backup.md | 0 7 files changed, 10 insertions(+), 4 deletions(-) rename doc/{ => book/src/dev}/dnsseed-policy.md (100%) rename doc/{ => book/src/user}/files.md (100%) rename doc/{ => book/src/user}/security-warnings.md (100%) rename doc/{ => book/src/user}/shield-coinbase.md (100%) rename doc/{ => book/src/user}/tor.md (100%) rename doc/{ => book/src/user}/wallet-backup.md (100%) diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md index 936925636..a80d31a8b 100644 --- a/doc/book/src/SUMMARY.md +++ b/doc/book/src/SUMMARY.md @@ -3,14 +3,20 @@ [zcashd](README.md) - [User Documentation](user.md) - [Platform Support](user/platform-support.md) + - [Wallet Backup](user/wallet-backup.md) + - [Shielding Coinbase Outputs](user/shield-coinbase.md) + - [Data Directory Structure](user/files.md) - [Metrics](user/metrics.md) + - [Using `zcashd` with Tor](user/tor.md) + - [Security Warnings](user/security-warnings.md) - [Deprecated Features](user/deprecation.md) - [Developer Documentation](dev.md) + - [DNS Seeders](dev/dnsseed-policy.md) - [Rust in `zcashd`](dev/rust.md) - - [Regtest tips and hints](dev/regtest.md) + - [Regtest Tips And Hints](dev/regtest.md) - [Platform Tier Policy](dev/platform-tier-policy.md) - [Deprecation Procedure](dev/deprecation.md) - [Design](design.md) - - [Chain state](design/chain-state.md) - - ["Coins" view](design/coins-view.md) - - [P2P data propagation](design/p2p-data-propagation.md) + - [Chain State](design/chain-state.md) + - ["Coins" View](design/coins-view.md) + - [P2P Data Propagation](design/p2p-data-propagation.md) diff --git a/doc/dnsseed-policy.md b/doc/book/src/dev/dnsseed-policy.md similarity index 100% rename from doc/dnsseed-policy.md rename to doc/book/src/dev/dnsseed-policy.md diff --git a/doc/files.md b/doc/book/src/user/files.md similarity index 100% rename from doc/files.md rename to doc/book/src/user/files.md diff --git a/doc/security-warnings.md b/doc/book/src/user/security-warnings.md similarity index 100% rename from doc/security-warnings.md rename to doc/book/src/user/security-warnings.md diff --git a/doc/shield-coinbase.md b/doc/book/src/user/shield-coinbase.md similarity index 100% rename from doc/shield-coinbase.md rename to doc/book/src/user/shield-coinbase.md diff --git a/doc/tor.md b/doc/book/src/user/tor.md similarity index 100% rename from doc/tor.md rename to doc/book/src/user/tor.md diff --git a/doc/wallet-backup.md b/doc/book/src/user/wallet-backup.md similarity index 100% rename from doc/wallet-backup.md rename to doc/book/src/user/wallet-backup.md From a6c05f1a28ec152a629da1e67f420e237aa80fc3 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Tue, 30 Aug 2022 14:39:37 +0100 Subject: [PATCH 6/7] Apply suggestions from code review --- doc/book/src/user/files.md | 3 ++- doc/book/src/user/security-warnings.md | 11 +++-------- 2 files changed, 5 insertions(+), 9 deletions(-) diff --git a/doc/book/src/user/files.md b/doc/book/src/user/files.md index dfde08fb2..418c2bd67 100644 --- a/doc/book/src/user/files.md +++ b/doc/book/src/user/files.md @@ -1,7 +1,8 @@ Data Directory Files ==================== -Files within the zcashd data directory (``~/.zcash/``) on Linux unless otherwise specified) include: +Files within the zcashd data directory (``~/.zcash/`` on Linux unless otherwise specified) +include: | File | Description |-----------------------|-------------- diff --git a/doc/book/src/user/security-warnings.md b/doc/book/src/user/security-warnings.md index 62beeb4fb..3e81a8b10 100644 --- a/doc/book/src/user/security-warnings.md +++ b/doc/book/src/user/security-warnings.md @@ -8,14 +8,6 @@ Zcash has been subjected to a formal third-party security review. For security announcements, audit results and other general security information, see https://z.cash/support/security.html -x86-64 Linux Only ------------------ - -There are [known bugs](https://github.com/scipr-lab/libsnark/issues/26/) -which make proving keys generated on 64-bit systems unusable on 32-bit and -big-endian systems. It's unclear if a warning will be issued in this case, or -if the proving system will be silently compromised. - Wallet Encryption ----------------- @@ -75,6 +67,9 @@ The REST interface is a feature inherited from upstream Bitcoin. By default, it is disabled. We do not recommend you enable it until it has undergone a security review. +RPC Interface +--------------- + Users should choose a strong RPC password. If no RPC username and password are set, zcashd will not start and will print an error message with a suggestion for a strong random password. If the client knows the RPC password, they have From 2621efd0dac69d976294d18a3113289ff0c5b1c8 Mon Sep 17 00:00:00 2001 From: Daira Hopwood Date: Tue, 30 Aug 2022 14:40:34 +0100 Subject: [PATCH 7/7] Update doc/book/src/user/security-warnings.md --- doc/book/src/user/security-warnings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/book/src/user/security-warnings.md b/doc/book/src/user/security-warnings.md index 3e81a8b10..63f050ce5 100644 --- a/doc/book/src/user/security-warnings.md +++ b/doc/book/src/user/security-warnings.md @@ -68,7 +68,7 @@ it is disabled. We do not recommend you enable it until it has undergone a security review. RPC Interface ---------------- +------------- Users should choose a strong RPC password. If no RPC username and password are set, zcashd will not start and will print an error message with a suggestion