|
|
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.
| |