|
|
| Line 1: |
Line 1: |
| == JSON-RPC Over SSL Setup ==
| | JSON-RPC over SSL is strongly discouraged |
| | |
| 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:
| |
| rpcallowip=10.11.13.15
| |
| rpcallowip=10.11.13.16
| |
| You may also allow connections from any IP address in a subnet using *:
| |
| rpcallowip=192.168.1.*
| |
| rpcallowip=10.1.*.*
| |
| You can also specify 'rpcallowip=*' to allow all IP addresses.
| |
| | |
| Connections from the local host (127.0.0.1) are always allowed.
| |
| | |
| 3. You must tell bitcoin to use ssl using the "rpcssl" configuration file option.
| |
| | |
| Edit the bitcoin.conf file, and add:
| |
| rpcssl=1
| |
| | |
| 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.
| |
| | |
| [[Category:Technical]]
| |
| [[Category:Developer]]
| |
| | |
| == 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:
| |
| | |
| {| class="wikitable"
| |
| |-
| |
| ! 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
| |
| |-
| |
| | rpcssl || -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 April 2011, 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:
| |
| rpcsslciphers=DEFAULT:@STRENGTH
| |
| in the bitcoin.conf file.
| |
JSON-RPC over SSL is strongly discouraged