Bitcoin Wiki - User contributions [en]

CVE-2012-3789

2013-01-08T21:17:09Z

Basinga: typo s/maga/mega/g

== Multiple DoS Vulnerabilties in Satoshi Bitcoin client ==

Private Release Date: 12-MAY-2012 
Public Release Date: 08-JAN-2013 

=== Systems Affected ===
----------------

- Satoshi Bitcoin Client (Bitcoin-Qt, bitcoind) 
- All Bitcoin clients that mimic Satoshi client behaviour related to orphan transactions 

=== Affected Versions ===
-----------------

- Bitcoin version 0.5.3, released 14 March 2012 
- Bitcoin version 0.5.3.1 released 16 March 2012 
- Bitcoin version 0.6.0 released 30 March 2012 
- Bitcoin version 0.6.1 released 4 May 2012 
- Bitcoin version 0.6.2 released 8 May 2012 

=== Overview ===
--------

This report contains information regarding two new vulnerabilities discovered in May-2012. The more severe one allows a
connected peer to hang the victim's client application in less than 20 minutes by sending a stream of specially
crafted transactions, as a denial-of-service attack.

=== Background ===
----------

Each peer defines a transaction as "Orphan" if the transaction references a parent transaction (previous output) which is
neither part of a block in the current best chain, nor it is in the in-memory transaction pool.
Before version 0.5.3 of Satoshi Bitcoin client, orphan transactions were stored in a temporary table in memory until the parent transactions could be located in a block or the parent transaction was forwarded by a peer.
The storage for ophan transaction was unlimited. This feature allowed an attacker to perform a DoS attack by sending transactions continuously until the victim's virtual memory was filled and the victim's operating system began trashing. This situation probably leads to the victim's computer or application to hang.
The time needed for this DoS attack varies depending on the link bandwidth between the attacker and the victim, and the victim's RAM size. For an average computer and Internet connection it takes approximately 12 hours.

The vulnerability was discovered by Sergio Demian Lerner and communicated to the Bitcoin.org development team, who developed and applied a patch (https://github.com/bitcoin/bitcoin/pull/911) that was incorporated in version 0.5.3.
The patch limits the number of orphan transactions that are stored in memory and randomly erases a previous stored transaction on the arrival of a new one, if the memory table becomes full.

Unfortunately the patch is ineffective and allows two new vectors of attack that are more severe than the original attack. The patched version still allows an attacker to fill the victim's memory with orphan transactions (see vulnerability 1) and it also allows an attacker to hang the victim's client application (see vulnerability 2) in less than 20 minutes.

=== Vulnerability 1 Details ===
-----------------------

Orphan transactions are stored in the table mapOrphanTransactions. The patch limits the number of entries to 10000 (constant MAX_ORPHAN_TRANSACTIONS). This number is arbitrary, and the criteria for the selection of the constant is unknown. Because transactions are not limited in size, is easy to create an orphan transaction whose size reaches
1 megabyte. If the transaction is built with thousands of random inputs (prevouts which are unknown to the victim app) then also the table mapOrphanTransactionsByPrev can fill the entire RAM. Prevouts whose hash is chosen at random would make trashing worse since virtual memory page faults will become inevitable.

Suppose the attacker wants the victim to store 4 Gigabytes of data in virtual memory. Assume a 50 Kb/sec connection bandwidth.
Then the attack takes approximately 11 hours.

=== Patching vulnerability 1 ===
------------------------

The application must limit the amount of memory used by tables mapOrphanTransactions and mapOrphanTransactionsByPrev, either by counting the number of bytes used or by limiting the maximum size of each orphan transaction.

Added note: Bitcoin version 0.6.3 and later only store orphan transactions whose size is less than 5000 byles. This limits the amount of memory that mapOrphanTransactions can consume, totalling no more than 50 Mbytes. Since the "map" data structure has a significant overhead when storing a single element, 5000 transactions that link to many random missing previns can force mapOrphanTransactionsByPrev to consume as high as 200 additional megabytes.

Some extra security provisions may be implemented:

* Prioritize orphan transactions that provide a proof of work per input (network protocol must be changed).
* Limit the amount of transactions that each peer can send depending on the peer connection time (older peers get more bandwidth)

=== Vulnerability 2 Details ===
-----------------------

Each time a transaction must be erased from mapOrphanTransactions, all references to parent transactions must be erased from the table mapOrphanTransactionsByPrev too (see EraseOrphanTx()). The method wrongly assumes that the number of
associations between a parent transaction and its potential childs is low, and so the code iterates through all pairs parent/child until the transaction to be erased is found. Code excerpt:

BOOST_FOREACH(const CTxIn& txin, tx.vin)
{
for (multimap<uint256, CDataStream*>::iterator mi = mapOrphanTransactionsByPrev.lower_bound(txin.prevout.hash);
mi != mapOrphanTransactionsByPrev.upper_bound(txin.prevout.hash);)
{
if ((*mi).second == pvMsg)
mapOrphanTransactionsByPrev.erase(mi++);
else
mi++;
}
}

Each reference to a previous transaction is specified by a prevout, which is a hash of the transaction and an index of the outpoint referred. An attacker can send 10000 transactions that whose inputs refer to the same parent transaction (same hash), but specifying different indexes. Index numbers can be chosen incrementally (from 1 to 1M) since indexes cannot be verified to be out of range for a (still unknown) parent transaction.

The attack is strengthened by the fact that client applications do not check for empty scripts in inputs, so each input size can be as low as 41 bytes. 11K transaction containing 100 fake inputs each is enough to hang a Satoshi client in an Intel Core 2 CPU 4300 running on a local testnet in less than a minute. If a connection of 50 Kb/sec is assumed, then the attack takes less than 20 minutes. Note that only one core of the CPU gets 100% of usage, because the client runs a single thread to process all messages from peers. Simulations were carried on on a local testnet, so the outcome of the attack on a real node (with plenty of peer connections) was not evaluated.

=== Patching vulnerability 2 ===
------------------------

One possible change is to modify the mapOrphanTransactionsByPrev data structure from:

multimap<uint256, CDataStream*> mapOrphanTransactionsByPrev;

to:

map<uint256, map<uint256,CDataStream*> > mapOrphanTransactionsByPrev;

Example new EraseOrphanTx() method (not tested):

void static EraseOrphanTx(uint256 hash)
{
if (!mapOrphanTransactions.count(hash))
return;
const CDataStream* pvMsg = mapOrphanTransactions[hash];
CTransaction tx;
BOOST_FOREACH(const CTxIn& txin, tx.vin)
{
mapOrphanTransactionsByPrev[txin.prevout.hash].erase(hash);
}
mapOrphanTransactions.erase(hash);
}

Added note: Bitcoin version 0.6.3 and later includes this modification.

=== Disclosure Timeline ===
-------------------

* 2012-05-12 - Vulnerability reported to Gavin Andressen
* 2012-05-17 - Gavin Andressen patches ready for review
* 2012-06-20 - 0.6.3rc1 available for testing
* 2012-06-25 - Bitcoin version 0.6.3 released, fixing the vulnerabilities.
* 2013-01-08 - Vulnerability disclosure

=== Credit ===
------

This vulnerability was discovered by Sergio Demian Lerner, from Certimix.com, who also did
the vulnerability research and report editing for the public good.

API reference (JSON-RPC)

2012-08-22T17:14:42Z

Basinga: change ruby code example

== Controlling Bitcoin ==

Run ''bitcoind'' or ''bitcoin -server''. You can control it via the command-line or by [http://json-rpc.org/wiki/specification HTTP JSON-RPC] commands.

You must create a bitcoin.conf configuration file setting an rpcuser and rpcpassword; see [[Running Bitcoin]] for details.

Now run:
$ ./bitcoind
bitcoin server starting
$ ./bitcoind help
# shows the help text

A [[Original Bitcoin client/API Calls list|list of RPC calls]] will be shown.

$ ./bitcoind getbalance
2000.00000

== JSON-RPC ==

Running Bitcoin with the -server argument (or running bitcoind) tells it to function as a [http://json-rpc.org/wiki/specification HTTP JSON-RPC] server, but
[http://en.wikipedia.org/wiki/Basic_access_authentication Basic access authentication] must be used when communicating with it, and, for security, by default, the server only accepts connections from other processes on the same machine. If your HTTP or JSON library requires you to specify which 'realm' is authenticated, use 'jsonrpc'.

Bitcoin supports SSL (https) JSON-RPC connections beginning with version 0.3.14. See the [[Enabling SSL on original client daemon|rpcssl wiki page]] for setup instructions and a list of all bitcoin.conf configuration options.

To access the server you should find a [http://json-rpc.org/wiki/implementations suitable library] for your language.

== Proper money handling ==

See the [[Proper Money Handling (JSON-RPC)|proper money handling page]] for notes on avoiding rounding errors when handling bitcoin values.

== Python ==

[http://json-rpc.org/wiki/python-json-rpc python-jsonrpc] is the official JSON-RPC implementation for Python.
It automatically generates Python methods for RPC calls.
However, due to its design for supporting old versions of Python, it is also rather inefficient.
[[User:jgarzik|jgarzik]] has forked it as [https://github.com/jgarzik/python-bitcoinrpc Python-BitcoinRPC] and optimized it for current versions.
Generally, this version is recommended.

While BitcoinRPC lacks a few obscure features from jsonrpc, software using only the ServiceProxy class can be written the same to work with either version the user might choose to install:

<source lang="python">
from jsonrpc import ServiceProxy

access = ServiceProxy("http://user:password@127.0.0.1:8332")
access.getinfo()
access.listreceivedbyaddress(6)
#access.sendtoaddress("11yEmxiMso2RsFVfBcCa616npBvGgxiBX", 10)
</source>

== Ruby ==

<source lang="ruby">
require 'net/http'
require 'uri'
require 'json'

class BitcoinRPC
def initialize(service_url)
@uri = URI.parse(service_url)
end

def method_missing(name, *args)
post_body = { 'method' => name, 'params' => args, 'id' => 'jsonrpc' }.to_json
resp = JSON.parse( http_post_request(post_body) )
raise JSONRPCError, resp['error'] if resp['error']
resp['result']
end

def http_post_request(post_body)
http = Net::HTTP.new(@uri.host, @uri.port)
request = Net::HTTP::Post.new(@uri.request_uri)
request.basic_auth @uri.user, @uri.password
request.content_type = 'application/json'
request.body = post_body
http.request(request).body
end

class JSONRPCError < RuntimeError; end
end

if $0 == __FILE__
h = BitcoinRPC.new('http://user:password@127.0.0.1:8332')
p h.getbalance
p h.getinfo
p h.getnewaddress
p h.dumpprivkey( h.getnewaddress )
# also see: https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_Calls_list
end
</source>

== PHP ==

The [http://jsonrpcphp.org/ JSON-RPC PHP] library also makes it very easy to connect to Bitcoin. For example:

<source lang="php">
require_once 'jsonRPCClient.php';

$bitcoin = new jsonRPCClient('http://user:password@127.0.0.1:8332/');

echo "<pre>\n";
print_r($bitcoin->getinfo()); echo "\n";
echo "Received: ".$bitcoin->getreceivedbylabel("Your Address")."\n";
echo "</pre>";
</source>

== Java ==

The easiest way to tell Java to use HTTP Basic authentication is to set a default Authenticator:

<source lang="java">
final String rpcuser ="...";
final String rpcpassword ="...";

Authenticator.setDefault(new Authenticator() {
protected PasswordAuthentication getPasswordAuthentication() {
return new PasswordAuthentication (rpcuser, rpcpassword.toCharArray());
}
});
</source>

Once that is done, any JSON-RPC library for Java (or ordinary URL POSTs) may be used to communicate with the Bitcoin server.

== Perl ==

The JSON::RPC package from CPAN can be used to communicate with Bitcoin. You must set the client's credentials; for example:

<source lang="perl">
use JSON::RPC::Client;
use Data::Dumper;

my $client = new JSON::RPC::Client;

$client->ua->credentials(
'localhost:8332', 'jsonrpc', 'user' => 'password' # REPLACE WITH YOUR bitcoin.conf rpcuser/rpcpassword
);

my $uri = 'http://localhost:8332/';
my $obj = {
method => 'getinfo',
params => [],
};

my $res = $client->call( $uri, $obj );

if ($res){
if ($res->is_error) { print "Error : ", $res->error_message; }
else { print Dumper($res->result); }
} else {
print $client->status_line;
}
</source>

== .NET (C#) ==
The communication with rpc service can be achieved using the standard httprequest/response objects.
A library for serialising and deserialising Json will make your life a lot easier:

* JayRock for .NET 4.0
* Json.Net for .NET 2.0 and above

The following example uses Json.Net:

<source lang="csharp">
HttpWebRequest webRequest = (HttpWebRequest)WebRequest.Create("http://localhost.:8332");
webRequest.Credentials = new NetworkCredential("user", "pwd");
/// important, otherwise the service can't desirialse your request properly
webRequest.ContentType = "application/json-rpc";
webRequest.Method = "POST";

JObject joe = new JObject();
joe.Add(new JProperty("jsonrpc", "1.0"));
joe.Add(new JProperty("id", "1"));
joe.Add(new JProperty("method", Method));
// params is a collection values which the method requires..
if (Params.Keys.Count == 0)
{
joe.Add(new JProperty("params", new JArray()));
}
else
{
JArray props = new JArray();
// add the props in the reverse order!
for (int i = Params.Keys.Count - 1; i >= 0; i--)
{
.... // add the params
}
joe.Add(new JProperty("params", props));
}

// serialize json for the request
string s = JsonConvert.SerializeObject(joe);
byte[] byteArray = Encoding.UTF8.GetBytes(s);
webRequest.ContentLength = byteArray.Length;
Stream dataStream = webRequest.GetRequestStream();
dataStream.Write(byteArray, 0, byteArray.Length);
dataStream.Close();

WebResponse webResponse = webRequest.GetResponse();

... // deserialze the response
</source>

There is also a wrapper for Json.NET called Bitnet (https://sourceforge.net/projects/bitnet)
implementing Bitcoin API in more convenient way:

<source lang="csharp">
BitnetClient bc = new BitnetClient("http://127.0.0.1:8332");
bc.Credentials = new NetworkCredential("user", "pass");

var p = bc.GetDifficulty();
Console.WriteLine("Difficulty:" + p.ToString());

var inf = bc.GetInfo();
Console.WriteLine("Balance:" + inf["balance"]);
</source>

== Node.js ==
There are two unofficial node.js modules for interacting with the bitcoin client.

* [https://github.com/freewil/node-bitcoin node-bitcoin] (npm: bitcoin)
* [https://github.com/Weltschmerz/Kapitalize Kapitalize] (npm: kapitalize)

Example using node-bitcoin:

<source lang="javascript">
var bitcoin = require('bitcoin');
var client = new bitcoin.Client({
host: 'localhost',
port: 8332,
user: 'user',
pass: 'pass'
});

client.getDifficulty(function(err, difficulty) {
if (err) {
console.log('Error...');
console.log(err);
return;
}

console.log('Difficulty: ' + difficulty);
});
</source>

Example using Kapitalize:

<source lang='javascript'>
var client = require('kapitalize')()

client.auth('user', 'password')

client
.getInfo()
.getDifficulty(function(err, difficulty) {
console.log('Dificulty: ', difficulty)
})
</source>

== Command line (cURL) ==

You can also send commands and see results using [http://curl.haxx.se/ cURL] or some other command-line HTTP-fetching utility; for example:

<source lang="bash">
curl --user user --data-binary '{"jsonrpc": "1.0", "id":"curltest", "method": "getinfo", "params": [] }'
-H 'content-type: text/plain;' http://127.0.0.1:8332/
</source>

You will be prompted for your rpcpassword, and then will see something like:

<source lang="javascript">
{"result":{"balance":0.000000000000000,"blocks":59952,"connections":48,"proxy":"","generate":false,
"genproclimit":-1,"difficulty":16.61907875185736,"error":null,"id":"curltest"}
</source>

== See Also==

* [[Original_Bitcoin_client/API_Calls_list|API calls list]]
* [[Running Bitcoin]]
* [[Lazy API]]
* [[PHP developer intro]]
* [[Raw_Transactions|Raw Transactions API]]

[[Category:Technical]]
[[Category:Developer]]
[[zh-cn:API_reference_(JSON-RPC)]]