What's JSON-RPC?

JSON-RPC is a lightweight remote procedure call protocol. It's designed to be simple!

The general mechanism consists of two peers establishing a data connection. During the lifetime of a connection, peers may invoke methods provided by the other peer. To invoke a remote method, a request is sent. Unless the request is a notification it must be replied to with a response. From JSON RPC Spec.

JSON-RPC & bitcoind

Bitcoin started accepting SSL JSON-RPC connections beginning with version 0.3.14 in order to remotely invoke bitcoin protocol functions. (from Bitcoin wiki)

When using a JSON-RPC client to communicate with bitcoind running a JSON-RPC server, security is very important in order to protect against man in the middle (MITM) attacks.

Tools Required

In order to securely use JSON-RPC with bitcoind you'll need the following items installed

Installation Process

First you will need to generate a valid certificate using OpenSSL. If you already have a certificate from a certificate authority, you can simply import it. To create a certificate, do the following on your server:

cd ~/.bitcoin
openssl genrsa -out server.pem 2048
openssl req -new -x509 -nodes -sha1 -days 3650 -key server.pem > server.cert

Lets now break these commands down to understand what we are doing.

  • The first command openssl is telling the terminal we want to use openssl and pass arguments to it. Next is “genrsa” we are telling openssl that we are going to make a RSA key pair which we know is the foundation of SSL and secure connections. Then we use -out server.pem, which means to write it to a file called server.pem. The last part is 2048 this is how many bits we want it, you want 2048, that is a standard strong key pair.
  • In the second openssl command, we are telling openssl to create a new x509 certificate, and to input a sha1 fingerprint into the certificate. Then we are using the key from the previously created server.pem to create the server.cert, our certificate. Do not enter a passphrase if prompted too just hit enter again.

The next step is to configure bitcoind. To do this, do the following commands:

  • Open the ~/.bitcoin/bitcoin.conf file in any text editor.
  • Add the line "rpcallowip=IP_ADDRESS" line and put in the IP address of the client that you want to allow connections from to the JSON-RPC server.
  • Add the line "rpcssl=1" to tell bitcoind we want to accept SSL request
  • Restart bitcoind
  • Run "openssl s_client -connect localhost:8332" to test if the changes were accepted.
  • Copy the server.cert file to the client machine and verify that you can connect to the JSON-RPC server.