Enabling SSL on original client daemon

From Bitcoin Wiki
Revision as of 17:32, 22 April 2011 by Gavinandresen (talk | contribs) (Ported from old wiki)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

By default, bitcoin allows JSON-RPC commands to be sent to http://localhost:8332/, and accepts connections only from the local host.

It can be configured to allow https connections from other hosts; three things must be setup for this to work properly:

1. You must setup a server certificate and private key. A self-signed certificate will work nicely, you don't need to pay for a certificate signed by a certificate authority.

By default, bitcoin looks for the server's private key file in a "server.pem" in the bitcoin data directory (e.g. ~/.bitcoin/server.pem on unix), and the server certificate file in "server.cert". To generate them using the openssl command-line program, run:

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

You should NOT enter a passphrase.

2. Specify the IP addresses of clients that are allowed to connect using "rpcallowip" configuration file options.

Edit the bitcoin.conf file (in the bitcoin data directory), and add a line for each IP address allowed to connect:


You may also allow connections from any IP address in a subnet using *:


You can also specify 'rpcallowip=*' to allow all IP addresses.

Connections from the local host ( are always allowed.

3. You must tell bitcoin to use ssl using the "rpcssl" configuration file option.

Edit the bitcoin.conf file, and add:


Restart bitcoin or bitcoind to make these changes take effect. You can test bitcoin's ssl functionality using the openssl s_client command:

 openssl s_client -connect localhost:8332

The connection should be successful and you should see the server's certificate details. If you press return twice, you should get a 'HTTP/1.0 401 Authorization Required' response.

Client setup

Once the server is accepting https connections, to be secure you should make sure the client is actually connecting to the bitcoin server and not an attacker trying to hijack the connection.

If you can, you should copy the server.cert certificate chain file to the client machine and use it to validate the OpenSSL connection. For example, in php you would call stream_context_create() with the 'verify_peer' and 'ca_file' options and then call stream_context_set_default().

If you can't validate using the server certificate, you should connect to the server using its IP address instead of its host name.

bitcoin.conf Options

All HTTPS-JSON-RPC-related bitcoin.conf options:

Option Default Description
rpcport 8332 Listen for connections on this port
rpcuser -none- user name for HTTP BASIC authentication
rpcpassword -none- password for HTTP BASIC authentication
rpcssll -none- Not set by default, if set bitcoin will only accept SSL connections
rpcallowip -none- Allow a client at this IP address to connect (may be specified multiple times)
rpcsslciphers TLSv1+HIGH:!SSLv2:!aNULL:!eNULL:!AH:!3DES:@STRENGTH See the openSSL documentation for syntax
rpcsslcertificatechainfile server.cert File containing server's public key
rpcsslprivatekeyfile server.pem File containing server's private key
Known Problems

As of October 2010, Google's App Engine urlfetch service only supports the following ciphers: RC4-MD5, RC4-SHA, DES-CBC3-SHA None of those are secure enough to match the default rpcsslciphers list. The workaround is to specify:


in the bitcoin.conf file.